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:all	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
Supported Editions	SaaS / Marketplace	SaaS	SaaS
Documentation Details	See the User API Reference	See below	See below

For Marketplace Edition Users

The only connection method available in the Marketplace edition is Chat API / SSE. MCP and A2A are exclusive to the SaaS edition.

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 SaaS — When connecting from MCP-compatible AI agents like Claude to AGENTIC STAR. Agents automatically retrieve tool definitions.
• A2A SaaS — When connecting from Google A2A-compatible agents 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 in message.parts[] with kind: "text"

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

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.

Protocol	Cancellation Method
Chat API / SSE	POST /v1/chat/completions/{conversationId}/cancel
MCP (SaaS only)	Call the cancel_chat tool
A2A (SaaS only)	Send the tasks/cancel method

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.

User API Reference (Chat)

Endpoint specification, request body, response headers

→

SSE Streaming Guide

Connection flow, Delta extensions, execution patterns, error handling

→

MCP (Model Context Protocol) SaaS

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, and cancellation in AGENTIC STAR.

Connection Specification

Item	Value
Endpoint	POST /v1/mcp
Protocol	Streamable HTTP / JSON-RPC 2.0
Authentication	Bearer JWT (scope: mcp:all)
Mode	Stateless

Tool List

Tool Name	Scope	Description
execute_chat	mcp:all	Send a task to the agent and retrieve execution results
get_file_content	mcp:all	Download deliverable files generated by the agent
cancel_chat	mcp:all	Cancel an in-progress task

Connection Configuration Example

Add the following to your MCP client configuration file.

JSON

{
  "mcpServers": {
    "agenticstar": {
      "url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}

A2A (Agent-to-Agent Protocol) SaaS

An interface for connecting Google A2A protocol-compatible agents 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:all)

Skill List

Skill Name	Scope	Description
execute_task	a2a:all	Send a task to the agent for autonomous execution (agentMode: true)
direct_llm	a2a:all	Query LLM directly (agentMode: false)

Supported Methods

Method	Description
message/send	Send a message and wait for completion
message/stream	Send a message and receive streaming via SSE
tasks/get	Retrieve task status
tasks/cancel	Cancel a task
tasks/resubscribe	Reattach to task streaming after an SSE disconnect (resume in progress)

Specifying Execution Parameters

To pass agentMode / agentLevel 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"
    }
  }
}

Both fields are optional. When omitted, the defaults agentMode: true / agentLevel: "default" are used.

Agent Card

A2A clients retrieve Agent Card from the following URL to automatically understand skills, authentication methods, and capabilities.

GET https://api.fd.agenticstar.tm.softbank.jp/.well-known/agent-card.json