Connection Methods Guide
This guide explains the three connection methods for interacting with AGENTIC STAR agents and the concepts common to all of them.
Three Connection Methods
You can interact with AGENTIC STAR agents through three methods depending on your use case. With any method, the basic structure of requests sent to agents and responses returned is the same.
| Chat API / SSE | MCP | A2A | |
|---|---|---|---|
| Protocol | REST + SSE | Streamable HTTP / JSON-RPC | JSON-RPC |
| Endpoint | /v1/chat/completions | /v1/mcp | /v1/a2a/agents/{agentId}/, /v1/a2a/projects/{projectId}/ |
| Token | Application or system integration | Application or system integration | Application or system integration |
| Discovery | None (see API spec) | Auto-discovered via tools/list | Agent Card (token required) |
| Target Clients | Your apps / HTTP clients | MCP-capable AI clients such as Claude Code and Codex | Agents and applications that support A2A |
| Detailed Docs | See the User API Reference and the System Integration API Reference | See below | See below |
Choosing a Method
- Chat API / SSE — When embedding agent capabilities into your own application. You have full control over requests and responses.
- MCP — When connecting to AGENTIC STAR from MCP-capable AI clients such as Claude Code and Codex. The client auto-discovers tool definitions. MCP is available only in environments where an administrator has opened the MCP inbound endpoint.
- A2A — When calling registered Agents or published workflows from external agents and applications that support A2A. A2A is available only in environments where an administrator has opened the inbound endpoints and set the standard token endpoint.
Common Request Parameters
Across all three connection methods, requests sent to agents are internally converted to the same format. The following parameters are available for all methods.
Within A2A, the endpoint of a published workflow differs from the common shape in this section (one message starts one run, and there are no files, conversation continuation, questions, or canceling). See the A2A API Reference.
The parameter names below are conceptual common names. The actual keys and structure differ per method:
- Chat API / SSE:
messages[].content(OpenAI-compatible format) - MCP:
promptin tool arguments - A2A:
textof the text parts inmessage.parts[](withkind: "text"on 0.3, withoutkindon 1.0)
For details, see each method's section (Chat API / MCP / A2A).
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Required | Instruction text to send to the agent |
agentId | string | Required | ID of the registered Agent to run. For MCP, specify an agentId returned by list_agents. For A2A, it is the {agentId} in the endpoint URL. |
conversationId | string | — | Specify to continue an existing conversation. If omitted, a new conversation is created. |
files | array | — | Attached files. For Chat API, pre-upload + fileId; for MCP, send with base64 encoding. |
Response Model
Regardless of the connection method, agent responses include the following information. The format varies by protocol, and for some elements the delivery form (single field / split into events) also differs per method. See each method's section for details.
| Element | Description |
|---|---|
text | Agent response text |
conversationId | Conversation ID. Specify in your next request to continue the conversation. |
deliverables | List of deliverable files generated by the agent (filename, path, MIME type, etc.) |
executionSteps | Agent execution trace (step details like tool calls and code execution) |
interaction | Interaction request to user (only when applicable) |
Interactions
Interactions occur when the agent needs user input during task execution. Clients should present options or confirmations to users based on the interaction type and send responses with the same conversationId to continue the conversation.
| Type | Description | Client Action |
|---|---|---|
choice | Present options and ask the user to select one | Send selection as text |
confirmation | Ask the user for confirmation (approve/deny) | Send approval/denial as text |
question | Asks the user to answer one or more prompts | Send the answers as text. Even prompts that offer choices carry those choices in the body text |
For the specific SSE format, see Streaming Guide — Interactions.
Continuing Conversations
Interactions with agents are managed by conversationId. By specifying the conversationId from the response in your next request, you can maintain context for continuous dialogue. If you omit conversationId, a new conversation starts.
You cannot send multiple simultaneous requests to the same conversationId (HTTP 409 Conflict). Wait for the previous request to complete or cancel it before sending a new request.
Cancellation
You can cancel an in-progress agent execution. The cancellation method varies by connection method.
| Protocol | Cancellation Method | Target Specification |
|---|---|---|
| Chat API / SSE | POST /v1/chat/completions/{conversationId}/cancel | Path parameter conversationId |
| MCP | cancel_chat tool | Argument conversationId |
| A2A (registered Agent) | tasks/cancel (0.3) / CancelTask (1.0) | In params.id, the conversation ID on 0.3 and the task ID on 1.0 |
All three methods converge on the same underlying cancellation process. With A2A, canceling a task that has already finished returns TaskNotCancelableError (JSON-RPC error code -32002). On 0.3, a task waiting for a reply cannot be canceled either (on 1.0 it can). The MCP cancel_chat tool does not raise an error when the run has already finished; it returns completed or not_found in conversationState.
Chat API / SSE
An OpenAI-compatible Chat Completions API. Call directly from HTTP clients and receive responses in real-time via SSE (Server-Sent Events) streaming. For detailed specifications on requests and responses, see the User API Reference.
MCP (Model Context Protocol)
The interface for connecting to AGENTIC STAR from MCP-capable AI clients (such as Claude Code and Codex). The client auto-discovers tool definitions on connection, and sends requests to registered Agents, retrieves files, cancels runs, works with projects, and runs published workflows.
Connection Specifications
| Item | Value |
|---|---|
| Endpoint | POST /v1/mcp |
| Protocol | Streamable HTTP / JSON-RPC 2.0 |
| Authentication | Bearer JWT (a user token of an application, or a system integration token; no scope restrictions) |
| Mode | Stateless |
For the tools, see MCP API Reference — Provided Tools. For how to configure and connect AI clients, see the AI Client Connection Guide (MCP).
A2A (Agent-to-Agent Protocol)
An interface for calling AGENTIC STAR's registered Agents and published workflows from external agents and applications that support A2A (0.3 and 1.0). Each registered Agent and each published workflow has its own endpoint and Agent Card, and clients retrieve the skills and authentication methods from the Agent Card.
Connection Specifications
| Item | Value |
|---|---|
| Endpoint (registered Agent) | POST /v1/a2a/agents/{agentId}/ |
| Endpoint (published workflow) | POST /v1/a2a/projects/{projectId}/ |
| Agent Card | .well-known/agent-card.json under each endpoint (token required) |
| Protocol | JSON-RPC 2.0 |
| Authentication | Bearer JWT (a user token of an application, or a system integration token; no scope restrictions) |
The registered Agent endpoint advances tasks in a conversation, as chat does. The published workflow endpoint starts one run per message. For methods, input, and errors, see the A2A API Reference.