--- title: "Handle Agent RPC by Name" method: POST path: "/agents/name/{agent_name}/rpc" tags: ["Agents"] --- # Handle Agent RPC by Name `POST /agents/name/{agent_name}/rpc` Handle JSON-RPC requests for an agent by its unique name. ## Path parameters - `agent_name` string, required ## Request body - AgentRPCRequest - `jsonrpc` '2.0' - `method` 'event/send' | 'task/create' | 'message/send' | 'task/cancel' | 'task/interrupt', required - `params` union, required — The parameters for the agent RPC request - CreateTaskRequest - `name` string, nullable — Optional human-readable name for the task. When set it must be globally unique. task/create is get-or-create by name: reusing an existing name returns the existing task (with its prior history) instead of creating a new one, so omit name (or make it unique, e.g. by appending a UUID) whenever each call should produce a fresh task. - `params` object, nullable — The parameters for the task. On a get-or-create by name, providing params overwrites the existing task's params (it is not a pure read). - `task_metadata` object, nullable — Caller-provided metadata to persist on the task row. Only applied at task creation; ignored if a task with this name already exists. Forwarded to the agent inside the ACP payload for backward compatibility. - CancelTaskRequest - `task_id` string, nullable — The ID of the task to cancel. Either this or task_name must be provided. - `task_name` string, nullable — The name of the task to cancel. Either this or task_id must be provided. - InterruptTaskRequest - `task_id` string, nullable — The ID of the task to interrupt. Either this or task_name must be provided. - `task_name` string, nullable — The name of the task to interrupt. Either this or task_id must be provided. - SendMessageRequest - `task_id` string, nullable — The ID of the task that the message was sent to - `task_name` string, nullable — The name of the task that the message was sent to - `content` union, required - TextContent - `type` 'text' — The type of the message, in this case `text`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `format` 'markdown' | 'plain' | 'code' - `content` string, required — The contents of the text message. - `attachments` FileAttachment[], nullable — Optional list of file attachments with structured metadata. - `file_id` string, required — The unique ID of the attached file - `name` string, required — The name of the file - `size` integer, required — The size of the file in bytes - `type` string, required — The MIME type or content type of the file - ReasoningContent - `type` 'reasoning' — The type of the message, in this case `reasoning`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `summary` string[], required — A list of short reasoning summaries - `content` string[], nullable — The reasoning content or chain-of-thought text - DataContent - `type` 'data' — The type of the message, in this case `data`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `data` object, required — The contents of the data message. - ToolRequestContent - `type` 'tool_request' — The type of the message, in this case `tool_request`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being requested. - `name` string, required — The name of the tool that is being requested. - `arguments` object, required — The arguments to the tool. - ToolResponseContent - `type` 'tool_response' — The type of the message, in this case `tool_response`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being responded to. - `name` string, required — The name of the tool that is being responded to. - `content` unknown, required - `is_error` boolean, nullable — Whether the tool call resulted in an error. `None` when the harness does not report a status. - `stream` boolean — Whether to stream the response message back to the client - `task_params` object, nullable — The parameters for the task (only used when creating new tasks) - SendEventRequest - `task_id` string, nullable — The ID of the task that the event was sent to - `task_name` string, nullable — The name of the task that the event was sent to - `content` union - TextContent - `type` 'text' — The type of the message, in this case `text`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `format` 'markdown' | 'plain' | 'code' - `content` string, required — The contents of the text message. - `attachments` FileAttachment[], nullable — Optional list of file attachments with structured metadata. - `file_id` string, required — The unique ID of the attached file - `name` string, required — The name of the file - `size` integer, required — The size of the file in bytes - `type` string, required — The MIME type or content type of the file - ReasoningContent - `type` 'reasoning' — The type of the message, in this case `reasoning`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `summary` string[], required — A list of short reasoning summaries - `content` string[], nullable — The reasoning content or chain-of-thought text - DataContent - `type` 'data' — The type of the message, in this case `data`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `data` object, required — The contents of the data message. - ToolRequestContent - `type` 'tool_request' — The type of the message, in this case `tool_request`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being requested. - `name` string, required — The name of the tool that is being requested. - `arguments` object, required — The arguments to the tool. - ToolResponseContent - `type` 'tool_response' — The type of the message, in this case `tool_response`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being responded to. - `name` string, required — The name of the tool that is being responded to. - `content` unknown, required - `is_error` boolean, nullable — Whether the tool call resulted in an error. `None` when the harness does not report a status. - `id` union - integer - string ## Response `200` Successful Response - AgentRPCResponse - `jsonrpc` '2.0' - `result` union, required - TaskMessage[] - `id` string, nullable — The task message's unique id - `task_id` string, required — ID of the task this message belongs to - `content` union, required - TextContent - `type` 'text' — The type of the message, in this case `text`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `format` 'markdown' | 'plain' | 'code' - `content` string, required — The contents of the text message. - `attachments` FileAttachment[], nullable — Optional list of file attachments with structured metadata. - `file_id` string, required — The unique ID of the attached file - `name` string, required — The name of the file - `size` integer, required — The size of the file in bytes - `type` string, required — The MIME type or content type of the file - ReasoningContent - `type` 'reasoning' — The type of the message, in this case `reasoning`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `summary` string[], required — A list of short reasoning summaries - `content` string[], nullable — The reasoning content or chain-of-thought text - DataContent - `type` 'data' — The type of the message, in this case `data`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `data` object, required — The contents of the data message. - ToolRequestContent - `type` 'tool_request' — The type of the message, in this case `tool_request`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being requested. - `name` string, required — The name of the tool that is being requested. - `arguments` object, required — The arguments to the tool. - ToolResponseContent - `type` 'tool_response' — The type of the message, in this case `tool_response`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being responded to. - `name` string, required — The name of the tool that is being responded to. - `content` unknown, required - `is_error` boolean, nullable — Whether the tool call resulted in an error. `None` when the harness does not report a status. - `streaming_status` 'IN_PROGRESS' | 'DONE', nullable - `created_at` string, date-time, nullable — The timestamp when the message was created - `updated_at` string, date-time, nullable — The timestamp when the message was last updated - union - StreamTaskMessageStart — Event for starting a streaming message - `type` 'start' - `index` integer, nullable - `parent_task_message` TaskMessage — Represents a message in the agent system. This entity is used to store messages in MongoDB, with each message associated with a specific task. - `id` string, nullable — The task message's unique id - `task_id` string, required — ID of the task this message belongs to - `content` union, required - TextContent - … - ReasoningContent - … - DataContent - … - ToolRequestContent - … - ToolResponseContent - … - `streaming_status` 'IN_PROGRESS' | 'DONE', nullable - `created_at` string, date-time, nullable — The timestamp when the message was created - `updated_at` string, date-time, nullable — The timestamp when the message was last updated - `content` union, required - TextContent - `type` 'text' — The type of the message, in this case `text`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `format` 'markdown' | 'plain' | 'code' - `content` string, required — The contents of the text message. - `attachments` FileAttachment[], nullable — Optional list of file attachments with structured metadata. - … - ReasoningContent - `type` 'reasoning' — The type of the message, in this case `reasoning`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `summary` string[], required — A list of short reasoning summaries - `content` string[], nullable — The reasoning content or chain-of-thought text - DataContent - `type` 'data' — The type of the message, in this case `data`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `data` object, required — The contents of the data message. - ToolRequestContent - `type` 'tool_request' — The type of the message, in this case `tool_request`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being requested. - `name` string, required — The name of the tool that is being requested. - `arguments` object, required — The arguments to the tool. - ToolResponseContent - `type` 'tool_response' — The type of the message, in this case `tool_response`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being responded to. - `name` string, required — The name of the tool that is being responded to. - `content` unknown, required - `is_error` boolean, nullable — Whether the tool call resulted in an error. `None` when the harness does not report a status. - StreamTaskMessageDelta — Event for streaming chunks of content - `type` 'delta' - `index` integer, nullable - `parent_task_message` TaskMessage — Represents a message in the agent system. This entity is used to store messages in MongoDB, with each message associated with a specific task. - `id` string, nullable — The task message's unique id - `task_id` string, required — ID of the task this message belongs to - `content` union, required - TextContent - … - ReasoningContent - … - DataContent - … - ToolRequestContent - … - ToolResponseContent - … - `streaming_status` 'IN_PROGRESS' | 'DONE', nullable - `created_at` string, date-time, nullable — The timestamp when the message was created - `updated_at` string, date-time, nullable — The timestamp when the message was last updated - `delta` union - TextDelta — Delta for text updates - `type` 'text' - `text_delta` string, nullable - DataDelta — Delta for data updates - `type` 'data' - `data_delta` string, nullable - ToolRequestDelta — Delta for tool request updates - `type` 'tool_request' - `tool_call_id` string, required - `name` string, required - `arguments_delta` string, nullable - ToolResponseDelta — Delta for tool response updates - `type` 'tool_response' - `tool_call_id` string, required - `name` string, required - `content_delta` string, nullable - ReasoningSummaryDelta — Delta for reasoning summary updates - `type` 'reasoning_summary' - `summary_index` integer, required - `summary_delta` string, nullable - ReasoningContentDelta — Delta for reasoning content updates - `type` 'reasoning_content' - `content_index` integer, required - `content_delta` string, nullable - StreamTaskMessageFull — Event for streaming the full content - `type` 'full' - `index` integer, nullable - `parent_task_message` TaskMessage — Represents a message in the agent system. This entity is used to store messages in MongoDB, with each message associated with a specific task. - `id` string, nullable — The task message's unique id - `task_id` string, required — ID of the task this message belongs to - `content` union, required - TextContent - … - ReasoningContent - … - DataContent - … - ToolRequestContent - … - ToolResponseContent - … - `streaming_status` 'IN_PROGRESS' | 'DONE', nullable - `created_at` string, date-time, nullable — The timestamp when the message was created - `updated_at` string, date-time, nullable — The timestamp when the message was last updated - `content` union, required - TextContent - `type` 'text' — The type of the message, in this case `text`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `format` 'markdown' | 'plain' | 'code' - `content` string, required — The contents of the text message. - `attachments` FileAttachment[], nullable — Optional list of file attachments with structured metadata. - … - ReasoningContent - `type` 'reasoning' — The type of the message, in this case `reasoning`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `summary` string[], required — A list of short reasoning summaries - `content` string[], nullable — The reasoning content or chain-of-thought text - DataContent - `type` 'data' — The type of the message, in this case `data`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `data` object, required — The contents of the data message. - ToolRequestContent - `type` 'tool_request' — The type of the message, in this case `tool_request`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being requested. - `name` string, required — The name of the tool that is being requested. - `arguments` object, required — The arguments to the tool. - ToolResponseContent - `type` 'tool_response' — The type of the message, in this case `tool_response`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being responded to. - `name` string, required — The name of the tool that is being responded to. - `content` unknown, required - `is_error` boolean, nullable — Whether the tool call resulted in an error. `None` when the harness does not report a status. - StreamTaskMessageDone — Event for indicating the task is done - `type` 'done' - `index` integer, nullable - `parent_task_message` TaskMessage — Represents a message in the agent system. This entity is used to store messages in MongoDB, with each message associated with a specific task. - `id` string, nullable — The task message's unique id - `task_id` string, required — ID of the task this message belongs to - `content` union, required - TextContent - … - ReasoningContent - … - DataContent - … - ToolRequestContent - … - ToolResponseContent - … - `streaming_status` 'IN_PROGRESS' | 'DONE', nullable - `created_at` string, date-time, nullable — The timestamp when the message was created - `updated_at` string, date-time, nullable — The timestamp when the message was last updated - Task - `id` string, required - `name` string, nullable - `status` 'CANCELED' | 'COMPLETED' | 'FAILED' | 'RUNNING' | 'INTERRUPTED' | 'TERMINATED' | 'TIMED_OUT' | 'DELETED' - `status_reason` string, nullable - `created_at` string, date-time, nullable - `updated_at` string, date-time, nullable - `cleaned_at` string, date-time, nullable - `params` object, nullable - `task_metadata` object, nullable - Event - `id` string, required — The UUID of the event - `sequence_id` integer, required — The sequence ID of the event - `task_id` string, required — The UUID of the task that the event belongs to - `agent_id` string, required — The UUID of the agent that the event belongs to - `created_at` string, date-time, nullable — The timestamp of the event - `content` union - TextContent - `type` 'text' — The type of the message, in this case `text`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `format` 'markdown' | 'plain' | 'code' - `content` string, required — The contents of the text message. - `attachments` FileAttachment[], nullable — Optional list of file attachments with structured metadata. - `file_id` string, required — The unique ID of the attached file - `name` string, required — The name of the file - `size` integer, required — The size of the file in bytes - `type` string, required — The MIME type or content type of the file - ReasoningContent - `type` 'reasoning' — The type of the message, in this case `reasoning`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `summary` string[], required — A list of short reasoning summaries - `content` string[], nullable — The reasoning content or chain-of-thought text - DataContent - `type` 'data' — The type of the message, in this case `data`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `data` object, required — The contents of the data message. - ToolRequestContent - `type` 'tool_request' — The type of the message, in this case `tool_request`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being requested. - `name` string, required — The name of the tool that is being requested. - `arguments` object, required — The arguments to the tool. - ToolResponseContent - `type` 'tool_response' — The type of the message, in this case `tool_response`. - `author` 'user' | 'agent', required - `style` 'static' | 'active' - `tool_call_id` string, required — The ID of the tool call that is being responded to. - `name` string, required — The name of the tool that is being responded to. - `content` unknown, required - `is_error` boolean, nullable — Whether the tool call resulted in an error. `None` when the harness does not report a status. - `error` unknown - `id` union - integer - string ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/scaleapi/apis/agentex-api.md) · [All operations](https://skmtc.net/scaleapi/apis/agentex-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scaleapi/agentex-api/versions/8f725ddc153e/schema)