Agent to agent

Agents can work with other agents in two ways. Use orchestration to coordinate your own agents inside one organization. Use A2A federation to let agents in other systems discover and call yours over the open Agent-to-Agent protocol.

Orchestration: coordinate your own agents

One request runs several agents toward a single goal. The platform selects agents by capability or by explicit id, runs them under a strategy, and returns a single run you can track.

POST /api/v1/agents/orchestrations
Authorization: Bearer <token>
Content-Type: application/json

{
  "description": "Research, then debate, whether to adopt Kubernetes now.",
  "strategy": "hierarchical",
  "capabilities": ["research.question.answer", "debate.decision.evaluate"],
  "continue_on_error": false,
  "timeout_seconds": 600,
  "max_assignments": 8
}

Key fields:

description (required): the goal, in plain language.
strategy: how agents run together.
- sequential: one after another, each seeing prior output.
- parallel: all at once, results merged.
- hierarchical: a manager agent plans and delegates to specialists.
- auto: the platform picks based on the request.
capabilities and/or agent_ids: which agents are eligible.
sub_tasks: an explicit task graph with depends_on edges, when you want to define the plan yourself instead of letting a strategy build it.
manager_agent_id: pin the coordinator for hierarchical.
continue_on_error, timeout_seconds, max_assignments: run controls.

The call returns 202 Accepted with a run_id. Track it:

GET /api/v1/agents/orchestrations/{run_id}
Authorization: Bearer <token>

The run response carries per-assignment progress (expected, started, completed, failed) and, when finished, the combined result. Pass an Idempotency-Key header to make retried submissions safe.

A2A federation: be discovered and invoked

Agentic Suite speaks the open Agent-to-Agent protocol, so an agent here can be discovered and called by any A2A-compatible client, including agents running in other organizations or other platforms.

The A2A discovery and invoke endpoints are served at the site root and do not require a bearer token or API key, because the A2A protocol is meant for open, cross-boundary discovery. That has direct consequences:

Publishing is an explicit opt-in. An agent is only listed when its deployment is marked discoverable, and is only invokable when the deployment is enabled. Nothing is exposed until you deploy it for A2A.
Anyone who can reach /a2a/{deployment_id} can invoke that agent. Access is gated by the deployment being enabled, not by the caller’s identity or organization. Treat an enabled A2A deployment as public to whoever can reach the endpoint.
Protect it at the edge. Put the A2A endpoints behind a gateway, allowlist, or private network when the agents are not meant for the open internet, and only federate agents you intend external callers to run. Keep sensitive or privileged agents on the authenticated /api/v1 surface instead.

The rest of the platform is different: every /api/v1 endpoint requires authentication and is scoped to your organization. See Authentication.

Make an agent discoverable

Publish the agent through a deployment. Two flags control exposure:

enabled: the deployment can be invoked at /a2a/{deployment_id}.
is_discoverable: the deployment is also listed in the public agent card catalog. A deployment that is enabled but not discoverable is still invokable by anyone who knows its id, it just is not listed.

Deployments are managed under /api/v1/deployments and in the app.

Discover agents

Fetch the agent card. This endpoint is at the root, not under /api/v1.

GET /.well-known/agent.json

It returns the catalog of discoverable agents, each with its capabilities and an invoke URL. Fetch one deployment’s card with:

GET /.well-known/agent.json?deployment_id=<deployment_id>

Invoke an agent

Call the deployment’s A2A endpoint with a JSON-RPC 2.0 message/send request. This endpoint is unauthenticated by design (see the caution above), so only deploy agents here that you intend to be callable this way, and protect the endpoint at the network edge when appropriate.

POST /a2a/{deployment_id}
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        { "text": "{\"capability\": \"research.question.answer\", \"payload\": {\"question\": \"...\"}}" }
      ]
    }
  }
}

The response is a JSON-RPC result containing the task status and the agent’s reply. Because it follows the A2A spec, standard A2A clients can talk to it without any Agentic Suite-specific code.

Orchestration or federation?

Same organization, you control all the agents: orchestration. It is simpler and gives you one tracked run.
Crossing a trust or platform boundary: federation. The agent card plus the A2A endpoint let outside systems discover and call your agent over a standard protocol.

Next: MCP.