Connect an external agent

An external agent is an agent that runs on another platform — Microsoft Foundry Agent Service, Copilot Studio, Claude Managed Agents, IBM watsonx Orchestrate, OpenAI Responses, Amazon Bedrock AgentCore, LangSmith, Google Agent Runtime, Salesforce, ServiceNow, any A2A v1.0 / v0.3 server, or another Agentic Workforce ME deployment. You register it once per tenant with a provider, a protocol, write-only credentials, a trust level, a residency region and a cost model; your agents then use it as a tool (a2a:<slug>.<skill>), as a workflow step (external_agent node) or as a delegation target. Every call is one audited, metered task, and remote output re-enters a model only wrapped as untrusted content. The reverse direction — their platform calling one of your agents — is Call a platform agent from Foundry.

1. Lifecycle: connect → discover → test → grant → use

Console: Build → Integrations → External agents (a four-step wizard: Provider · Details · Preview · Test & grant). API: /v1/external-agents (admin for writes). Credentials are validated against the bag for the chosen auth_kind, encrypted at rest, decrypted only inside the Tool Gateway per call, and never returned.

curl -sS -X POST "https://<api-host>/v1/external-agents" \
  -H "Authorization: Bearer hive_…" -H "Content-Type: application/json" \
  -d '{
    "slug": "contract-risk",
    "name": "Contract Risk Analyst (Foundry)",
    "provider": "foundry",
    "protocol": "a2a-1.0",
    "provider_config": {
      "project_endpoint": "https://<account>.services.ai.azure.com/api/projects/<project>",
      "agent_name": "contract-risk-analyst",
      "region": "swedencentral"
    },
    "auth_kind": "entra_client_credentials",
    "credentials": {
      "tenant_id": "<entra tenant id>",
      "client_id": "<app registration client id>",
      "client_secret": "<client secret>",
      "scope": "https://ai.azure.com/.default"
    },
    "trust_level": "partner",
    "residency_region": "eu",
    "cost_model": { "kind": "per_call", "usd": 0.02 },
    "timeout_ms": 120000
  }'

curl -sS -X POST "https://<api-host>/v1/external-agents" \
  -H "Authorization: Bearer hive_…" -H "Content-Type: application/json" \
  -d '{
    "slug": "research-claude",
    "name": "Research agent (Claude Managed Agents)",
    "provider": "claude",
    "protocol": "native",
    "endpoint_url": "https://api.anthropic.com",
    "provider_config": {
      "mode": "sessions",
      "agent_id": "agent_…",
      "environment_id": "env_…"
    },
    "auth_kind": "api_key",
    "credentials": { "api_key": "<anthropic api key>" },
    "trust_level": "partner",
    "cost_model": { "kind": "per_session_hour", "usd": 0.08 }
  }'

curl -sS -X POST "https://<api-host>/v1/external-agents" \
  -H "Authorization: Bearer hive_…" -H "Content-Type: application/json" \
  -d '{
    "slug": "partner-agent",
    "name": "Partner agent (A2A)",
    "provider": "a2a",
    "protocol": "a2a-1.0",
    "card_url": "https://agents.partner.example/.well-known/agent-card.json",
    "auth_kind": "bearer",
    "credentials": { "token": "<their bearer token>" },
    "trust_level": "untrusted"
  }'

endpoint_url or card_url is required and SSRF-checked; registration does not need the remote to be up. Preview a card first and test the row after creating it:

# preview the card before registering (nothing is stored)
curl -sS -X POST "https://<api-host>/v1/external-agents/discover" \
  -H "Authorization: Bearer hive_…" -H "Content-Type: application/json" \
  -d '{"card_url":"https://agents.partner.example/.well-known/agent-card.json"}'
# → { name, description, skills[], capabilities, securitySchemes, protocol_versions, signature_verified }

# describe() + a no-op message (max $0.01); records health, audits external_agent.test
curl -sS -X POST "https://<api-host>/v1/external-agents/<id>/test" \
  -H "Authorization: Bearer hive_…"
# → { ok, latency_ms, negotiated_version, auth_outcome: ok|unauthorized|forbidden|skipped|error }

Nothing can call the agent until it is granted (default-deny). Grants address a skill id or *:

curl -sS -X POST "https://<api-host>/v1/tool-grants" \
  -H "Authorization: Bearer hive_…" -H "Content-Type: application/json" \
  -d '{
    "source": "a2a",
    "external_agent_id": "<id>",
    "agent_id": "<calling agent id>",
    "tool_pattern": "analyze",
    "effect": "allow"
  }'
# tool_pattern "*" grants every skill; omit agent_id for a workspace-wide grant

2. Provider cheat-sheet

3. Use it

As a tool in an agent run

Declare the remote in the manifest and grant it; the model sees one tool per skill (a2a:<slug>.<skillId>, ask when the card has none) with a { task, context? } input. HITL resolves as for any tool — rules, approval policies, the high-risk gate — then the trust floor is applied.

{
  "tools": { "a2a": [{ "agent": "contract-risk", "allow": ["ask"] }] },
  "hitl": {
    "rules": [{ "tool": "a2a:contract-risk.analyze", "action": "require_approval" }]
  }
}

As a workflow step

{
  "id": "risk",
  "type": "external_agent",
  "config": {
    "external_agent_id": "<id>",
    "skill_id": "analyze",
    "input_from": "extract",
    "mode": "sync",
    "timeout_ms": 120000,
    "require_result": "json",
    "output_schema": {
      "type": "object",
      "required": ["risk_level"],
      "properties": { "risk_level": { "enum": ["low", "medium", "high"] } }
    },
    "on_input_required": "gate"
  }
}

Output: outputs.<id> = { text, json?, artifacts?, remote_task_id, remote_context_id, cost_usd, status }. Every call is a run_steps row named a2a:<slug>.<skill>.

As a delegation target

{
  "schema_version": "2.12",
  "delegation": {
    "enabled": true,
    "external_agents": ["contract-risk"]
  }
}
// at run time the agent calls agent.delegate with target "external:contract-risk"

delegation.external_agents is default-deny (empty = none) and tighten-only across scopes. The call routes through the same gateway path, records a delegations row (no child run) and returns the wrapped remote output.

4. Governance

curl -sS -X PATCH "https://<api-host>/v1/tenants/current" \
  -H "Authorization: Bearer hive_…" -H "Content-Type: application/json" \
  -d '{"settings":{"external_agents":{"max_cost_usd_per_day":25}}}'

5. Observe

• Run replay: an external step shows provider, protocol, skill, remote status, latency, cost, copyable remote_task_id / remote_context_id, and “Open in provider console” when the row has a provider_config.console_url_template.
• Registry: GET /v1/external-agents/:id/tasks — ids, status, latency, cost, redacted error; never message content.
• Audit: external_agent.create/update/delete/test/refresh_card/card_changed/invoke/callback; the invoke row carries the remote task id and cost, never task text.

6. Limits today

• OpenAI Agents API sessions are not supported (use mode: responses); the Assistants API is sunset.
• Foundry: no streaming, text only, Entra authentication only.
• Copilot Studio Activity mode needs a delegated Entra token — Direct Line is the service-identity path; no per-turn usage is reported.
• Async / push-callback mode works with A2A-protocol agents; native adapters run sync or stream.
• Calls always use the registered service identity — on-behalf-of (per-user) identity propagation is roadmap (Phase 3).
• Trace context (traceparent) is forwarded when supplied; no producer fills it yet.