Edit

Call APIs as an agent in a fleet with the Auth SDK sidecar

In a fleet, the sidecar acquires app-only tokens for many agents with one blueprint credential. Look up the agent's identity in the agent directory, and pass it in the AgentIdentity parameter on each request. The request is otherwise the same as for a single agent.

Prerequisites

Configure the runtime sidecar

Configure the sidecar with the blueprint credential, as described in Configure the Auth SDK sidecar. Set AzureAd:ClientId to the fleet's blueprint client ID. Unlike the single-instance setup, the fleet runtime must enable GetAuthorizationHeaderUnauthenticated and define an app-only profile for each API:

{
  "Sidecar": {
    "AllowOverrides": {
      "GetAuthorizationHeaderUnauthenticated": true
    }
  },
  "DownstreamApis": {
    "custom-api": {
      "BaseUrl": "https://api.contoso.com/",
      "Scopes": [
        "api://<custom-api-client-id>/.default"
      ],
      "RequestAppToken": true
    }
  }
}

The sidecar accepts only local requests. Colocate the trusted runtime and its sidecar in the same network namespace, such as a Kubernetes pod. For Docker Compose, use network_mode: "service:sidecar" on the runtime container and call http://localhost:5000, not http://sidecar:5000. Don't publish the sidecar port.

With the override enabled, any process that can reach the sidecar can request a token for any agent in the fleet. Only trusted runtime code should reach the sidecar. If agents run untrusted or customer-supplied code, run them outside the sidecar's network namespace and route their token requests through runtime code that selects the agent identity.

Get a token for an agent

Resolve the agent identity from the runtime's own agent ID, never from a value in a request or in agent output:

import requests

SIDECAR_URL = "http://localhost:5000"


def authorization_header_for_agent(agent_id: str, api_name: str) -> str:
    registration = directory.find(agent_id)
    if registration is None:
        raise LookupError(f"Agent '{agent_id}' isn't provisioned.")

    response = requests.get(
        f"{SIDECAR_URL}/AuthorizationHeaderUnauthenticated/{api_name}",
        params={"AgentIdentity": registration["agent_identity_id"]},
        timeout=5,
    )
    response.raise_for_status()
    return response.json()["authorizationHeader"]


api_response = requests.get(
    "https://api.contoso.com/data",
    headers={"Authorization": authorization_header_for_agent(agent_id, "custom-api")},
    timeout=10,
)
api_response.raise_for_status()

Treat the returned authorizationHeader as a credential, and don't log it.

Call specific resources

Use the scopes and endpoints from the linked resource articles, while keeping the fleet's blueprint client ID and override settings. The single-instance requests omit AgentIdentity. In the fleet, call authorization_header_for_agent or authorizationHeaderForAgent for every resource to supply the identity selected from the directory.

Resource Guidance
Custom API Call a custom API as an agent
Azure services Call Azure services as an agent
Microsoft Graph Call Microsoft Graph as an agent

Next step

Call APIs as an agent's user account in a fleet with the Auth SDK sidecar