# 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

> **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, questions, or canceling). See the [A2A API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/a2a-ref.md).

> **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](#chat-api--sse) / [MCP](#mcpmodel-context-protocol) / [A2A](#a2aagent-to-agent-protocol)).

| 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/streaming-guide.md#deltainteraction).

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

[User API Reference (Chat)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference.md#chat)

[Endpoint specification, request body, response headers](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference.md#chat)

[→](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference.md#chat)

[SSE Streaming Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/streaming-guide.md)

[Connection flow, Delta extensions, execution patterns, error handling](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/streaming-guide.md)

[→](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/streaming-guide.md)

## 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/mcp-ref.md#provided-tools). For how to configure and connect AI clients, see the [AI Client Connection Guide (MCP)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/ai-client-guide.md).

## 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](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/a2a-ref.md).
