Conversation with Agents

This guide explains the three connection methods for interacting with AgenticStar agents and concepts common to all methods.

Three Connection Methods

You can interact with AgenticStar 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:exec`	`a2a:exec`
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	`API Reference →`	`Connection Guide ↓`	`Connection Guide ↓`

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 AgenticStar. Agents automatically retrieve tool definitions.
A2A — When connecting from Google A2A-compatible agents to AgenticStar. 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.

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.

Execution Paths

The agent automatically selects an execution path based on task complexity. No specification is needed on the developer side. All connection methods have the same behavior.

Simple Path

Path where the LLM generates responses directly. Used for normal chat responses and simple questions. Completes in seconds.

Complex Path

Path where agents autonomously execute tasks using tools. Used for long-duration tasks including web search, file operations, and code execution. Takes 30 seconds to several minutes.

Response Model

Regardless of the connection method, agent responses include the following information. The format varies by protocol, but the content is the same.

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

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	`Call the cancel_chat tool`
A2A	`Send the tasks/cancel method`

Task Data Model

A Task object is generated whenever an agent performs an action such as tool execution, file operations, or search. This data model is common across all Chat API / SSE, MCP, and A2A protocols.

Task Object Fields

Parameter	Type	Required	Description
`messageId`	`string`	✓	ID of the message the task belongs to
`conversationId`	`string`	✓	ID of the conversation the task belongs to
`actionType`	`string`	✓	Action type. See actionType list below for details
`status`	`string`	✓	Task status: "pending" \| "in_progress" \| "completed" \| "failed" \| "success" \| "error". Value varies by actionType and data path
`timestamp`	`number`	✓	Task timestamp (Unix milliseconds)
`createdAt`	`string`	✓	Task creation date/time (ISO 8601)
`updatedAt`	`string`	✓	Task update date/time (ISO 8601)
`title`	`string`		Task title (for display)
`description`	`string`		Detailed description of the task
`callId`	`string \| null`		Tool call ID. Links tool_start with corresponding tool_result. Null for file_operation / search_result / mcp_tool
`content`	`string`		Task output content
`metadata`	`object`		Task metadata. Contains different fields depending on actionType
`files`	`TaskFile[]`		Array of files associated with the task

TaskFile Object Fields

Parameter	Type	Description
`filename`	`string`	File name
`fileType`	`string`	File type: "image" \| "pdf" \| "pptx" \| "text" \| "video" \| "other"
`size`	`number`	File size (bytes)
`filepath`	`string`	File path (relative path or URL)

Task Lifecycle

tool_start is only sent for specific tools (local_assistant / generate_video / Sandbox). It can be linked with corresponding result events (tool_result, etc.) using callId. search_result / command_execution / mcp_tool / file_operation are sent independently without tool_start (callId is null).

JSON
// Pattern A: tool_start → tool_result pair (linked via callId)
// local_assistant / generate_video / Sandbox only
{ "actionType": "tool_start", "callId": "0cf24f34-...", ... }
{ "actionType": "tool_result", "callId": "0cf24f34-...", ... }

// Pattern B: Independent send (callId is null)
{ "actionType": "search_result", "callId": null, ... }
{ "actionType": "file_operation", "callId": null, ... }
{ "actionType": "mcp_tool", "callId": null, ... }

// Pattern C: No tool_start + callId present (LLM call_id preserved)
{ "actionType": "tool_result", "callId": "call_T3GIhcQQ...", ... }

actionType List

actionType indicates the task type. tool_start is only sent for specific tools, while others are sent independently as result events.

actionType	Phase	Description	Example Tools
`tool_start`	Start	Start notification for specific tool. Includes Sandbox preparation	local_assistant, generate_video, Sandbox
`tool_result`	Complete	Result of general tool execution. Identify tool type via metadata.sub_event_type	bash, read, write, edit, multiedit, grep, glob, ls, webfetch, task, local_assistant, generate_video, generation_image, create_slide
`search_result`	Complete	Web search completion result	search_web
`command_execution`	Complete	Shell command execution result	execute_command
`mcp_tool`	Complete	MCP tool execution result (no metadata)	mcp_tool, Perplexity
`file_operation`	Independent	File creation completion notification (includes files[])	—

metadata Structure by actionType

The metadata field content varies by actionType. Below are representative patterns.

tool_start

Start notification sent for local_assistant / generate_video / Sandbox.

JSON
{
  "actionType": "tool_start",
  "callId": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
  "title": "local assistant",
  "description": "Processing local_assistant",
  "status": "in_progress",
  "metadata": {
    "tool_name": "local_assistant",
    "call_id": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
    "status": "starting"
  }
}

search_result

metadata on web search completion includes search query, result count, and search results array.

JSON
{
  "actionType": "search_result",
  "status": "completed",
  "title": "Executed web search",
  "description": "Searched for \"AI market trends 2026\"",
  "metadata": {
    "query": "AI market trends 2026",
    "searchType": "web",
    "searchEngine": "brave",
    "resultCount": 5,
    "results": [
      { "title": "...", "url": "...", "description": "..." }
    ]
  },
  "timestamp": 1710410000000
}

command_execution

metadata for shell command execution includes command, exit code, and output.

JSON
{
  "actionType": "command_execution",
  "status": "success",
  "callId": null,
  "metadata": {
    "command": "npm test",
    "exitCode": 0,
    "output": "Tests passed: 42/42",
    "errorOutput": "",
    "workingDirectory": "/workspace"
  }
}

mcp_tool

MCP tool results do not include a metadata field. Tool information is set in title and description.

JSON
{
  "actionType": "mcp_tool",
  "status": "in_progress",
  "callId": null,
  "title": "Perplexity",
  "description": "Running Perplexity"
}

file_operation

Task on file creation completion includes a files[] array.

JSON
{
  "actionType": "file_operation",
  "status": "completed",
  "callId": null,
  "metadata": {
    "operationType": "create",
    "filePaths": ["/home/ubuntu/todo.md"]
  },
  "files": [{
    "filename": "todo.md",
    "fileType": "text",
    "size": 1918,
    "filepath": "/plans/conv-id/files/todo.md"
  }]
}

tool_result

metadata for general tool results includes tool-specific fields and sub_event_type. You can identify the tool type via sub_event_type.

bash (sub_event_type: bash_executed)

JSON
{
  "actionType": "tool_result",
  "callId": "call_T3GIhcQQft13amxdhcJ4cBDz",
  "title": "success",
  "description": "{'result': 'ok'}",
  "status": "in_progress",
  "metadata": {
    "tool_name": "bash",
    "call_id": "call_T3GIhcQQft13amxdhcJ4cBDz",
    "sub_event_type": "bash_executed",
    "command": "python3 script.py",
    "exit_code": 0,
    "stdout": "{'result': 'ok'}\n",
    "stderr": "",
    "status": "success",
    "duration_ms": 24,
    "working_dir": "/opt/.autonomous_agent/.sandbox-runtime",
    "title": "Execute: python3 script.py"
  }
}

write (sub_event_type: file_edited)

JSON
{
  "actionType": "tool_result",
  "title": "created",
  "description": "File created: /workspace/src/app.py",
  "status": "in_progress",
  "metadata": {
    "tool_name": "write",
    "sub_event_type": "file_edited",
    "file_path": "/workspace/src/app.py",
    "lines_written": 45,
    "status": "created"
  }
}

Representative Tool List

You can identify tool type via metadata.tool_name and metadata.sub_event_type from tool_result. Below are representative tools.

tool_name	Description
`bash`	Bash command execution
`read`	File reading
`write / edit / multiedit`	File writing/editing
`grep / glob / ls`	File search
`webfetch`	Web page retrieval
`task`	Subtask launch
`generate_video`	Video generation

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

Chat API Reference

Endpoint specification, request body, response headers

→

SSE Streaming Guide

Connection flow, Delta extensions, execution patterns, error handling

→

MCP (Model Context Protocol)

An interface for connecting MCP-compatible AI agents (like Claude) to AgenticStar. Agents automatically retrieve tool definitions on connection and autonomously perform task execution, file retrieval, and cancellation in AgenticStar.

Connection Specification


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

Tool List

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

Connection Configuration Example

Add the following to your MCP client configuration file.

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

A2A (Agent-to-Agent Protocol)

An interface for connecting Google A2A protocol-compatible agents to AgenticStar. Client agents automatically retrieve skill information from Agent Card and perform task submission, streaming, and cancellation.

Connection Specification


Agent Card	`GET /.well-known/agent-card.json`
Endpoint	`POST /v1/a2a`
Protocol	`JSON-RPC 2.0`
Authentication	`Bearer JWT (scope: a2a:exec)`

Skill List

Skill Name	Scope	Description
`execute_task`	`a2a:exec`	Send a task to the agent for autonomous execution (agentMode: true)
`direct_llm`	`a2a:exec`	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

Agent Card

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

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

Three Connection Methods​

How to Choose a Method​

Common Request Parameters​

Execution Paths​

Response Model​

Interactions​

Continuing Conversations​

Cancellation​

Task Data Model​

Task Object Fields​

TaskFile Object Fields​

Task Lifecycle​

actionType List​

metadata Structure by actionType​

tool_start​

search_result​

command_execution​

mcp_tool​

file_operation​

tool_result​

Representative Tool List​

Chat API / SSE​

MCP (Model Context Protocol)​

Connection Specification​

Tool List​

Connection Configuration Example​

A2A (Agent-to-Agent Protocol)​

Connection Specification​

Skill List​

Supported Methods​

Agent Card​

Three Connection Methods

How to Choose a Method

Common Request Parameters

Execution Paths

Response Model

Interactions

Continuing Conversations

Cancellation

Task Data Model

Task Object Fields

TaskFile Object Fields

Task Lifecycle

actionType List

metadata Structure by actionType

tool_start

search_result

command_execution

mcp_tool

file_operation

tool_result

Representative Tool List

Chat API / SSE

MCP (Model Context Protocol)

Connection Specification

Tool List

Connection Configuration Example

A2A (Agent-to-Agent Protocol)

Connection Specification

Skill List

Supported Methods

Agent Card