🍳 Cookbook: Secure A2A Communication¶

AI Agents in the Stargate network communicate via the A2A (Agent-to-Agent) protocol. This guide shows you how to secure your agent's API and safely call other agents using cryptographic identities.

🎯 Goal¶

Protect your agent's sensitive tools from unauthorized access.
Authenticate with Sentinel to get a machine token.
Call a remote agent securely.

🔐 Phase 1: Protecting Your Endpoints¶

The Traylinx Template includes a unified authentication middleware. You can restrict access to "Verified Machine Agents" only.

1. The Auth Dependency¶

Use the verify_unified_auth dependency in your FastAPI routes:

# app/api/endpoints/custom.py
from fastapi import APIRouter, Depends
from app.middleware.auth import verify_unified_auth, CallerIdentity

router = APIRouter()

@router.post("/v1/secure-tool")
async def secure_endpoint(caller: CallerIdentity = Depends(verify_unified_auth)):
    # This endpoint now requires:
    # 1. A valid X-Agent-Secret-Token
    # 2. A valid X-Agent-User-Id

    if not caller.is_agent:
        raise HTTPException(status_code=403, detail="Only Agents allowed")

    return {"status": "success", "agent_id": caller.id}

📡 Phase 2: Calling Remote Agents¶

To call another agent, you need to prove your identity. The TraylinxAuthClient handles this automatically.

1. Manual Request (Python SDK)¶

from traylinx_auth_client import make_a2a_request

# Sentinel credentials from .env
# TRAYLINX_CLIENT_ID=...
# TRAYLINX_CLIENT_SECRET=...

response = make_a2a_request(
    method="POST",
    url="https://other-agent.com/v1/execute",
    json={"input": "Hello expert agent"}
)

print(response) # JSON results

2. Built-in A2A Tool (Template Only)¶

If you are using the template, use the RemoteAgentCallTool. It handles tracing, correlation IDs, and error retries for you.

from app.tools.a2a import RemoteAgentCallTool

a2a_tool = RemoteAgentCallTool()
result = await a2a_tool.execute(
    target_url="https://expert-agent.traylinx.com",
    message="What is the weather in London?",
    context={"priority": "high"}
)

🕵️ Phase 3: Identity Verification¶

When an agent calls you, Sentinel verifies: 1. Token Validity: Is the token current and not revoked? 2. Ownership: Does the calling agent actually own the ID they claim? 3. Permissions: Is this agent authorized to talk to you?

Verifying the Caller locally¶

@router.post("/process")
async def process(caller: CallerIdentity = Depends(verify_unified_auth)):
    logger.info(f"Accepted request from Agent: {caller.id}")
    # caller.metadata contains additional info from Sentinel

⚙️ Configuration Reminder¶

Ensure your .env contains the Sentinel endpoints:

# Production Sentinel URL (A2A Auth)
TRAYLINX_API_BASE_URL=https://sentinel.traylinx.com

# Your Agent Credentials (from Console)
TRAYLINX_CLIENT_ID=ag-231cf...
TRAYLINX_CLIENT_SECRET=ts-98a21...

🚀 Pro Tip: Distributed Tracing¶

All A2A calls automatically propagate the X-Correlation-Id. If you have Langfuse enabled, you will see the entire multi-agent trace in your dashboard, even if the agents are running on different clouds! 🌐