Connection Guide
This guide explains the three connection methods for interacting with AGENTIC STAR agents and concepts common to all methods.
Three Connection Methods
You can interact with AGENTIC STAR agents using three different methods depending on your use case. Regardless of the method, the basic structure of requests sent to and responses received from agents 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 |
| Scope | chat:exec | mcp:connect / mcp:all | a2a:connect / a2a:all |
| Discovery | None (see API spec) | Auto-retrieved via tools/list | Auto-retrieved via Agent Card |
| Expected Clients | Own application / HTTP client | Claude / MCP-compatible AI agents | A2A-compatible AI agents |
| Documentation Details | See the User API Reference | See below | See below |
How to Choose a Method
- Chat API / SSE — When integrating agent functionality into your own application. You control requests and responses directly.
- MCP — When connecting from MCP-compatible AI agents like Claude to AGENTIC STAR. Agents automatically retrieve tool definitions.
- A2A — When connecting from agents that support A2A (0.3 and 1.0) to AGENTIC STAR. Agents automatically retrieve skills via Agent Card.
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.
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) - A mark that a message answers a question:
interactionReplyin the body for the Chat API, andinteractionReplyin the tool arguments for MCP. For A2A there is no mark: send the reply as the continuation of the task waiting for an answer (only when the question has an ID is it recorded as the answer, and can the number of a chosen option be sent inmetadata.optionIndex; when it has no ID, answer in text without a number)
For details, see each method's section (Chat API / MCP / A2A).
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt / text | string | Required | Instruction text to send to the agent |
conversationId | string | — | Specify to continue an existing conversation. If omitted, a new conversation is created. |
agentMode | boolean | — | true (default) = autonomous agent execution. false = direct LLM response. |
agentLevel | string | — | "default" (default) or "high_performance". Switches the LLM model used for agent reasoning. |
reportMode | string | — | "with" (default) or "without". Controls whether a work report is generated on completion. |
personaKey | string | — | Persona (response personality) for the agent. Specify a personaKey returned by GET /v1/personas (or MCP list_personas). Omit to apply none. |
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) |
uiResource | Metadata for UI produced by the agent (only when applicable). Depending on the method it arrives as delta.uiResource (Chat API), uiResources[] (MCP), or a ui-resource- artifact (A2A) |
draft | A draft made in the chat, as data containing the values needed to create or update it (only when applicable). Depending on the method it arrives as delta.draft (Chat API), drafts[] (MCP) or a data part of the ui-resource- artifact (A2A) |
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 |
When the question has an ID (interactionId), a reply can carry a mark that says which question it answers (answer a question without an ID in text, without a mark). With it, the reply is recorded as the answer to that question, and you can answer even after the monthly usage limit is used up. For an answer chosen from the options, also send the number of the chosen option (0 to 9, starting from 0).
| Method | Mark |
|---|---|
Chat API / SSE | interactionReply in the body ({ interactionId, optionIndex? }). interactionId is delta.interaction.interactionId |
MCP | interactionReply in the arguments of execute_chat (the same form). interactionId is interaction.interactionId in the result |
A2A | No mark. A reply sent as the continuation of the task waiting for an answer is recorded as the answer automatically when the question has an ID (metadata.interactionId). The number of a chosen option goes in metadata.optionIndex (only when the question has an ID) |
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 | 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)
An interface for connecting MCP-compatible AI agents (like Claude) to AGENTIC STAR. Agents automatically retrieve tool definitions on connection and autonomously perform task execution, file retrieval, cancellation, and project operations in AGENTIC STAR.
Connection Specification
| Item | Value |
|---|---|
| Endpoint | POST /v1/mcp |
| Protocol | Streamable HTTP / JSON-RPC 2.0 |
| Authentication | Bearer JWT (scope: mcp:connect or mcp:all) |
| Mode | Stateless |
For the tools and scopes, 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 connecting agents that support the A2A protocol (0.3 and 1.0) to AGENTIC STAR. Client agents automatically retrieve skill information from Agent Card and perform task submission, streaming, and cancellation.
Connection Specification
| Item | Value |
|---|---|
| Agent Card | GET /.well-known/agent-card.json |
| Endpoint | POST /v1/a2a |
| Protocol | JSON-RPC 2.0 |
| Authentication | Bearer JWT (scope: a2a:connect with the scope of each operation, or a2a:all) |
Skill List
| Skill Name | Scope | Description |
|---|---|---|
execute_task | a2a:all (or a2a:connect with chat:exec, plus chat:file when attaching files) | Send a task to the agent for autonomous execution (agentMode: true) |
direct_llm | a2a:all (or a2a:connect with chat:exec) | Query LLM directly (agentMode: false) |
Supported Methods
| 0.3 | 1.0 | Description |
|---|---|---|
message/send | SendMessage | Send a message and wait for completion |
message/stream | SendStreamingMessage | Send a message and receive streaming via SSE |
tasks/get | GetTask | Retrieve task status |
— | ListTasks | List the tasks of one conversation |
tasks/cancel | CancelTask | Cancel a task |
tasks/resubscribe | SubscribeToTask | Reattach to task streaming after an SSE disconnect |
Specifying Execution Parameters
To pass agentMode / agentLevel / reportMode / personaKey from the Common Request Parameters via A2A, set them as flat keys under message.metadata (declared in capabilities.extensions of the Agent Card).
{
"message": {
"parts": [{ "kind": "text", "text": "..." }],
"metadata": {
"agentMode": true,
"agentLevel": "high_performance",
"reportMode": "without",
"personaKey": "concise"
}
}
}
All fields are optional. When omitted, the defaults agentMode: true / agentLevel: "default" / reportMode: "with" are used, and omitting personaKey applies no persona.
Agent Card
A2A clients retrieve Agent Card from the following URL to automatically understand skills, authentication methods, and capabilities. There are two forms of the Agent Card: with the request header A2A-Version: 1.0 you get the 1.0 form only, and without it you get a single Agent Card that carries the fields of both 0.3 and 1.0 (A2A API Reference — Agent Card).
GET https://api.fd.agenticstar.tm.softbank.jp/.well-known/agent-card.json
Calling from Gemini Enterprise
These steps add AGENTIC STAR to the agent list of Google's Gemini Enterprise so that Gemini Enterprise users can ask AGENTIC STAR. Gemini Enterprise uses A2A 0.3, so the Agent Card above (retrieved without A2A-Version) is used as is. The screens on the Gemini Enterprise side are a Preview feature of Google.
- In the Console, create the app that Gemini Enterprise uses (Console Guide — Steps to Create an Application)
- Application type: Web Application
- Redirect URI:
https://vertexaisearch.cloud.google.com/oauth-redirectandhttps://vertexaisearch.cloud.google.com/static/oauth/oauth.html - Scopes:
a2a:connect,chat:exec,chat:history
- In the Gemini Enterprise app, open "Agents" > "Add Agents", choose "Custom agent via A2A", and paste the JSON of the Agent Card into "Agent card JSON"
- On the next screen, enter the Client ID and Client Secret of the app in 1, the authorization URL (Authorization URI) and the token URL (Token URI) in
securitySchemesof the Agent Card, and the scopes in 1
- The Gemini Enterprise locations are
global,usandeu - Traffic to an agent registered this way does not go through Google's Agent Gateway
- When an AGENTIC STAR administrator has stopped the agent, AGENTIC STAR refuses the calls even from Gemini Enterprise