Agents and A2A API

The agent Product API has two different surfaces. The A2A endpoints provide a stable discovery and runtime boundary. Agent management, builder, manifest, provider, task, automation, channel, memory, skill, and tool resources are currently exposed through workspace resource proxy routes and do not yet share one stable high-level request/response contract.

Discover an agent

GET /newmoi/agents/card

The Agent Card describes the agent identity and the A2A capabilities made available by the deployment. Read the card before constructing a client: supported message parts, task behavior, streaming, input requirements, and extensions must come from the returned card rather than assumptions.

The caller still needs X-Workspace-ID and valid workspace permission. An agent code or card from one workspace is not authorization to invoke the same name in another workspace.

Send A2A requests

POST /newmoi/agents/a2a

This endpoint is the product A2A runtime entry. Use the A2A method and payload defined by the deployment’s contract. The runtime supports the core task flow represented by product clients: send a message, read task state, cancel a task, and submit additional input when the task requests it.

For each request:

  • generate and retain a caller request ID;

  • use a caller-supplied message ID when the protocol requires one;

  • store the returned task and turn identifiers;

  • preserve text, data, file, and artifact parts as typed protocol parts;

  • treat a request for additional input as a non-terminal state;

  • stop polling or streaming only at a documented terminal task state.

A transport timeout does not prove that the agent did not create a task. Query using the task or request ID before sending the same prompt again. Canceling a task is also asynchronous until the task state confirms cancellation.

Streaming and artifacts

When the deployment enables streaming, parse events incrementally and maintain their order. A status update is not an answer part, and an artifact update can replace or append to prior content according to its metadata. Do not concatenate every event into plain text or discard artifact identifiers needed by a later call.

Agent output can contain external-tool results or links. Treat it as untrusted application data, validate URLs and file types, and do not execute returned commands automatically.

Agent management boundary

The following workspace-scoped route families are registered:

/newmoi/workspaces/:id/agents
/newmoi/workspaces/:id/agent-builder
/newmoi/workspaces/:id/agent-runtime
/newmoi/workspaces/:id/agent-runtime-manifests
/newmoi/workspaces/:id/agent-runtime-providers
/newmoi/workspaces/:id/agent-runtime-tasks

Related resource families cover automations, channels, memory, skills, and tools. These routes are currently generic backend-to-core proxies. Do not build a long-lived integration by guessing CRUD fields from UI traffic. Use the OpenAPI contract published by the target deployment, and require a stable product schema before automating resource lifecycle operations.

For external automation or channels, bind an immutable, tested agent version rather than a mutable draft. Confirm credentials, callback signatures, timezone, target permissions, and the latest deployment result before diagnosing a missed trigger.

Knowledge sources used by an agent are covered in Knowledge and Explore; model supply is covered in Models and providers.