Skip to main content

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 / SSEMCPA2A
ProtocolREST + SSEStreamable HTTP / JSON-RPCJSON-RPC
Endpoint/v1/chat/completions/v1/mcp/v1/a2a/agents/{agentId}/, /v1/a2a/projects/{projectId}/
TokenApplication or system integrationApplication or system integrationApplication or system integration
DiscoveryNone (see API spec)Auto-discovered via tools/listAgent Card (token required)
Target ClientsYour apps / HTTP clientsMCP-capable AI clients such as Claude Code and CodexAgents and applications that support A2A
Detailed DocsSee the User API Reference and the System Integration API ReferenceSee belowSee below

Choosing a Method​

Which method should I choose?
  • 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, or questions; canceling cancels that run). See the A2A API Reference.

Per-method request keys

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: prompt in tool arguments
  • A2A: text of the text parts in message.parts[] (with kind: "text" on 0.3, without kind on 1.0)

For details, see each method's section (Chat API / MCP / A2A).

ParameterTypeRequiredDescription
promptstringRequiredInstruction text to send to the agent
agentIdstringRequiredID of the registered Agent to run. In chat, use a marketplaceAgentId from GET /v1/marketplace-agents; in MCP, an agentId from list_agents. For A2A, it is the {agentId} in the endpoint URL.
conversationIdstring—Specify to continue an existing conversation. If omitted, a new conversation is created.
filesarray—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.

ElementDescription
textAgent response text
conversationIdConversation ID. Specify in your next request to continue the conversation.
deliverablesList of deliverable files generated by the agent (filename, path, MIME type, etc.)
executionStepsAgent execution trace (step details like tool calls and code execution)
interactionInteraction 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.

TypeDescriptionClient Action
choicePresent options and ask the user to select oneSend selection as text
confirmationAsk the user for confirmation (approve/deny)Send approval/denial as text
questionAsks the user to answer one or more promptsSend 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.

note

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.

ProtocolCancellation MethodTarget Specification
Chat API / SSEPOST /v1/chat/completions/{conversationId}/cancelPath parameter conversationId
MCPcancel_chat toolArgument 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​

ItemValue
EndpointPOST /v1/mcp
ProtocolStreamable HTTP / JSON-RPC 2.0
AuthenticationBearer JWT (a user token of an application, or a system integration token; no scope restrictions)
ModeStateless

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​

ItemValue
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)
ProtocolJSON-RPC 2.0
AuthenticationBearer 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.