Agents and A2A

MOI exposes a common Agent runtime through the Agent2Agent (A2A) protocol. A client first reads an Agent Card to discover an Agent’s identity and capabilities, then sends JSON-RPC messages. For longer work, the client can consume SSE events, inspect or cancel a Task, and resume a stream after a disconnect.

Current SDK coverage

The official MOI Python SDK and MOI Go SDK do not currently expose public types or methods for Agents, Agent Cards, A2A messages, or A2A Tasks.

Consequently:

  • Do not assume methods such as client.agents or send_message exist.

  • The Python SDK’s RawClient.get_json and post_json expect the MOI envelope used by Catalog APIs. Agent Card and A2A endpoints return protocol JSON directly, so those helpers are not substitutes for an A2A client.

  • The Go SDK’s generic JSON and low-level request methods are private implementation details and should not be called by applications.

  • Until typed support is added, use the language’s HTTP client or a maintained HTTP/SSE library with the same service URL, API key, and workspace context as your other MOI calls.

The request and response examples in this section describe the gateway’s current public HTTP contract. They do not imply that either SDK already implements corresponding methods.

Endpoints and methods

The MOI gateway has two Agent endpoints:

Purpose

HTTP request

Result

Retrieve an Agent Card

GET /newmoi/agents/card

Agent Card JSON

Invoke an Agent

POST /newmoi/agents/a2a

JSON-RPC response or SSE stream

POST /newmoi/agents/a2a currently accepts these A2A methods:

Method

Transport

Use

message/send

JSON

Send a message and wait for the current response

message/stream

SSE

Send a message and receive status and artifact updates

tasks/get

JSON

Read the latest state of an existing Task

tasks/cancel

JSON

Request cancellation of a Task that can still be canceled

tasks/resubscribe

SSE

Continue receiving updates after a recorded event sequence

Selecting an Agent

Every Card or A2A request must identify its target. Use the agent_code or agent_id supplied by the service; do not derive an identifier from the display name.

{
  "agent_code": "explore"
}

An Agent hosted in a particular Agent workspace may also require agent_workspace_id. This selects where the Agent is hosted and is not the caller’s current workspace. Obtain its value from the Agent publication configuration or a platform administrator rather than inferring it from a user workspace ID.

Call lifecycle

  1. Retrieve the Agent Card and check the selected Agent and capabilities.streaming.

  2. Generate unique IDs for the JSON-RPC request and user message.

  3. Send the message with message/send or message/stream.

  4. Save the Task id and contextId; for a stream, also save each SSE id.

  5. Inspect, cancel, or resubscribe to the Task when needed.

  6. Put the saved contextId on follow-up messages to continue the same conversation context.

An HTTP success only means that the gateway accepted and processed the protocol request. Determine business completion from the Task’s status.state and the received events.

Before integrating

  • Configure the service URL and API key as described in Authentication.

  • Confirm that the caller can access the current workspace and the target Agent’s knowledge bases, models, workflows, and tools.

  • Use a sufficiently long read timeout for streaming requests and disable response buffering in intermediate proxies.

  • Log the JSON-RPC id, Task id, contextId, and last SSE id, but never log the API key or sensitive message content.