Skip to main content

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 / SSEMCPA2A
ProtocolREST + SSEStreamable HTTP / JSON-RPCJSON-RPC
Endpoint/v1/chat/completions/v1/mcp/v1/a2a
Scopechat:execmcp:connect / mcp:alla2a:connect / a2a:all
DiscoveryNone (see API spec)Auto-retrieved via tools/listAuto-retrieved via Agent Card
Expected ClientsOwn application / HTTP clientClaude / MCP-compatible AI agentsA2A-compatible AI agents
Documentation DetailsSee the User API ReferenceSee belowSee below

How to Choose a Method​

Which method should you choose?
  • 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.

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)
  • A mark that a message answers a question: interactionReply in the body for the Chat API, and interactionReply in 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 in metadata.optionIndex; when it has no ID, answer in text without a number)

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

ParameterTypeRequiredDescription
prompt / textstringRequiredInstruction text to send to the agent
conversationIdstring—Specify to continue an existing conversation. If omitted, a new conversation is created.
agentModeboolean—true (default) = autonomous agent execution. false = direct LLM response.
agentLevelstring—"default" (default) or "high_performance". Switches the LLM model used for agent reasoning.
reportModestring—"with" (default) or "without". Controls whether a work report is generated on completion.
personaKeystring—Persona (response personality) for the agent. Specify a personaKey returned by GET /v1/personas (or MCP list_personas). Omit to apply none.
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)
uiResourceMetadata 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)
draftA 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.

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

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).

MethodMark
Chat API / SSEinteractionReply in the body ({ interactionId, optionIndex? }). interactionId is delta.interaction.interactionId
MCPinteractionReply in the arguments of execute_chat (the same form). interactionId is interaction.interactionId in the result
A2ANo 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.

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
A2Atasks/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​

ItemValue
EndpointPOST /v1/mcp
ProtocolStreamable HTTP / JSON-RPC 2.0
AuthenticationBearer JWT (scope: mcp:connect or mcp:all)
ModeStateless

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​

ItemValue
Agent CardGET /.well-known/agent-card.json
EndpointPOST /v1/a2a
ProtocolJSON-RPC 2.0
AuthenticationBearer JWT (scope: a2a:connect with the scope of each operation, or a2a:all)

Skill List​

Skill NameScopeDescription
execute_taska2a: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_llma2a:all (or a2a:connect with chat:exec)Query LLM directly (agentMode: false)

Supported Methods​

0.31.0Description
message/sendSendMessageSend a message and wait for completion
message/streamSendStreamingMessageSend a message and receive streaming via SSE
tasks/getGetTaskRetrieve task status
—ListTasksList the tasks of one conversation
tasks/cancelCancelTaskCancel a task
tasks/resubscribeSubscribeToTaskReattach 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).

JSON
{
"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.

  1. 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-redirect and https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
    • Scopes: a2a:connect, chat:exec, chat:history
  2. 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"
  3. 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 securitySchemes of the Agent Card, and the scopes in 1
  • The Gemini Enterprise locations are global, us and eu
  • 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