A2A endpoints & lifecycle

Hosted A2A URLs

External callers reach registered agents through the API gateway AI-core lane. The frontend builds URLs with the same rules as buildA2aUrl in the product:

Deployment status	URL pattern	Example shape
Live	`{gateway}/api/v1/ai/a2a/{flowId}`	Production routing; registry ID omitted
Test	`{gateway}/api/v1/ai/a2a/{flowId}/{registryId}`	Validation build tied to a specific registry row

# Live
https://app-dev.phinite.ai/api/v1/ai/a2a/{flowId}

# Test
https://app-dev.phinite.ai/api/v1/ai/a2a/{flowId}/{a2aregistryid}

Replace the host with your environment’s gateway base (NEXT_PUBLIC_BACKEND_SERVER_URL → /api/v1, then append /ai for the AI-core lane). Graph Studio and Agent Registry copy the authoritative string for your tenant—always use the value shown in the UI rather than constructing URLs manually. For local development with the dev API proxy, the same paths may appear under http://localhost:3000/api/v1/ai/a2a/....

Registry lifecycle

Each expose action creates an A2A registry row with deployment status test by default.

Status	Meaning	Hosted URL
`test`	Internal validation before broad discovery	Includes `{registryId}` in path
`live`	Production build for the agent graph	Short path with `{flowId}` only

One live build per agent graph per workspace. Promoting a build to live demotes any previous live row for the same flowid back to test.

Promote to live

From Agent Cards, select a test build and use Push To Prod (promote flow). The app calls:

PUT /api/v1/a2a-registry/{a2aregistryid}/promote-live

No request body is required. The response is the updated registry document with status: "live".

Visibility and authentication

Each Agent Card declares visibility:

Visibility	UI label	Invoke behaviour (high level)
`public`	Public	Callable by any client presenting a valid Phinite API key
`organization`	Organisation	Callable only when the API key belongs to the same organisation as the registry row

At runtime, the gateway A2ARegistryAccess middleware validates visibility when agents are invoked (for example POST /api/v1/ai/a2a/agents/{registryId}). Organisation-scoped agents return an auth error if the caller’s org does not match. Auth scheme in the product: callers use your organisation’s API key (JWT) in the X-API-Key header unless your deployment configures additional schemes.

External clients (Claude Connector)

End users can call registry agents from Claude via the Phinite Connector without constructing A2A URLs manually.

Layer	Behaviour
Connector auth	User signs in to Phinite (Google or email) when connecting the plugin in Claude
Discovery	`discover_agents` / `list_agents` query the same registry metadata as the workspace catalog
Invocation	`call_agent` maps to A2A `SendMessage` on `POST /api/v1/ai/a2a/agents/{registryId}`
Multi-turn	Pass `task_id` from a prior response to continue the same A2A task
Tool credentials	If the build requires integrations and no valid config exists, the runtime returns `TASK_STATE_AUTH_REQUIRED` with a link to `/public/agent-config`

Full install steps, tool parameters, and credential lifecycle: Invoke A2A agents from Claude.

Agent Card contract for integrators

Integrators and A2A-compatible clients should consume:

Agent name and description from the Agent Card
Skills — each skill lists supported input modes and output modes (MIME types)
Discoverability tags — for search and Discovery matching
Hosted URL — test vs live pattern above

See the Agent Registry glossary for supported MIME types. Official protocol details: A2A protocol specification.

Registry management API

All routes require gateway authentication (session cookie or Bearer token / API key). Base path: /api/v1/a2a-registry.

Method	Path	Purpose
`GET`	`/a2a-registry`	List registry rows (`workspaceid` required; optional `orgid`, `status`, `visibility`, `flowid`, filters)
`GET`	`/a2a-registry/{a2aregistryid}`	Get one row (`?flow=true` includes decrypted flow payload)
`POST`	`/a2a-registry?workspaceid=...`	Create registration (Expose wizard)
`PUT`	`/a2a-registry/{a2aregistryid}`	Update registration
`PUT`	`/a2a-registry/{a2aregistryid}/promote-live`	Promote to live
`DELETE`	`/a2a-registry/{a2aregistryid}`	Delete registration

Permissions (api-server): assistants.flows:read|create|update|delete depending on operation.

Useful list query parameters

Parameter	Values	Use
`workspaceid`	string	Required — scopes to workspace
`orgid`	string	Organisation filter (must match caller’s org)
`status`	`test`, `live`	Deployment filter
`visibility`	`public`, `organization`	Top-level visibility filter
`flowid`	string	All builds for one agent graph
`flow_list=true`	boolean	Returns distinct flows only (Agent Cards dropdown)
`pagination`	`true` / `false`	Paginated vs full list

Invoke from Claude

Phinite Connector install, tools, and credential setup.

Expose an agent

Create a test build and Agent Card.

Agent Cards

Promote test builds to live.

​Hosted A2A URLs

​Registry lifecycle

​Promote to live

​Visibility and authentication

​External clients (Claude Connector)

​Agent Card contract for integrators

​Registry management API

​Useful list query parameters

​Related pages