# Deployments ## Create Deployment **post** `/agents/{agent_id}/deployments` Create a new deployment record in PENDING status. ### Path Parameters - `agent_id: string` ### Body Parameters - `docker_image: string` Full Docker image URI. - `helm_release_name: optional string` Helm release name. - `registration_metadata: optional map[unknown]` Git/build metadata (commit_hash, branch_name, author_name, author_email, build_timestamp). - `sgp_deploy_id: optional string` SGP deployment ID. ### Returns - `id: string` The unique identifier of the deployment. - `agent_id: string` The agent this deployment belongs to. - `docker_image: string` Full Docker image URI. - `is_production: boolean` Whether this is the production deployment. - `status: "Pending" or "Ready" or "Failed"` Current deployment status. - `"Pending"` - `"Ready"` - `"Failed"` - `acp_url: optional string` ACP URL set when agent registers. - `created_at: optional string` When the deployment was created. - `expires_at: optional string` When marked for cleanup. - `helm_release_name: optional string` Helm release name for cleanup. - `promoted_at: optional string` When promoted to production. - `registration_metadata: optional map[unknown]` Git/build metadata from the agent pod. - `sgp_deploy_id: optional string` Correlates to SGP's agentex_deploys.id. ### Example ```http curl http://localhost:5003/agents/$AGENT_ID/deployments \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $AGENTEX_SDK_API_KEY" \ -d '{ "docker_image": "docker_image" }' ``` #### Response ```json { "id": "id", "agent_id": "agent_id", "docker_image": "docker_image", "is_production": true, "status": "Pending", "acp_url": "acp_url", "created_at": "2019-12-27T18:11:19.117Z", "expires_at": "2019-12-27T18:11:19.117Z", "helm_release_name": "helm_release_name", "promoted_at": "2019-12-27T18:11:19.117Z", "registration_metadata": { "foo": "bar" }, "sgp_deploy_id": "sgp_deploy_id" } ``` ## List Deployments **get** `/agents/{agent_id}/deployments` List deployments for an agent, newest first. ### Path Parameters - `agent_id: string` ### Query Parameters - `limit: optional number` Limit - `order_by: optional string` Field to order by - `order_direction: optional string` Order direction (asc or desc) - `page_number: optional number` Page number ### Returns - `id: string` The unique identifier of the deployment. - `agent_id: string` The agent this deployment belongs to. - `docker_image: string` Full Docker image URI. - `is_production: boolean` Whether this is the production deployment. - `status: "Pending" or "Ready" or "Failed"` Current deployment status. - `"Pending"` - `"Ready"` - `"Failed"` - `acp_url: optional string` ACP URL set when agent registers. - `created_at: optional string` When the deployment was created. - `expires_at: optional string` When marked for cleanup. - `helm_release_name: optional string` Helm release name for cleanup. - `promoted_at: optional string` When promoted to production. - `registration_metadata: optional map[unknown]` Git/build metadata from the agent pod. - `sgp_deploy_id: optional string` Correlates to SGP's agentex_deploys.id. ### Example ```http curl http://localhost:5003/agents/$AGENT_ID/deployments \ -H "Authorization: Bearer $AGENTEX_SDK_API_KEY" ``` #### Response ```json [ { "id": "id", "agent_id": "agent_id", "docker_image": "docker_image", "is_production": true, "status": "Pending", "acp_url": "acp_url", "created_at": "2019-12-27T18:11:19.117Z", "expires_at": "2019-12-27T18:11:19.117Z", "helm_release_name": "helm_release_name", "promoted_at": "2019-12-27T18:11:19.117Z", "registration_metadata": { "foo": "bar" }, "sgp_deploy_id": "sgp_deploy_id" } ] ``` ## Get Deployment **get** `/agents/{agent_id}/deployments/{deployment_id}` Get a specific deployment by ID. ### Path Parameters - `agent_id: string` - `deployment_id: string` ### Returns - `id: string` The unique identifier of the deployment. - `agent_id: string` The agent this deployment belongs to. - `docker_image: string` Full Docker image URI. - `is_production: boolean` Whether this is the production deployment. - `status: "Pending" or "Ready" or "Failed"` Current deployment status. - `"Pending"` - `"Ready"` - `"Failed"` - `acp_url: optional string` ACP URL set when agent registers. - `created_at: optional string` When the deployment was created. - `expires_at: optional string` When marked for cleanup. - `helm_release_name: optional string` Helm release name for cleanup. - `promoted_at: optional string` When promoted to production. - `registration_metadata: optional map[unknown]` Git/build metadata from the agent pod. - `sgp_deploy_id: optional string` Correlates to SGP's agentex_deploys.id. ### Example ```http curl http://localhost:5003/agents/$AGENT_ID/deployments/$DEPLOYMENT_ID \ -H "Authorization: Bearer $AGENTEX_SDK_API_KEY" ``` #### Response ```json { "id": "id", "agent_id": "agent_id", "docker_image": "docker_image", "is_production": true, "status": "Pending", "acp_url": "acp_url", "created_at": "2019-12-27T18:11:19.117Z", "expires_at": "2019-12-27T18:11:19.117Z", "helm_release_name": "helm_release_name", "promoted_at": "2019-12-27T18:11:19.117Z", "registration_metadata": { "foo": "bar" }, "sgp_deploy_id": "sgp_deploy_id" } ``` ## Delete Deployment **delete** `/agents/{agent_id}/deployments/{deployment_id}` Delete a non-production deployment. ### Path Parameters - `agent_id: string` - `deployment_id: string` ### Returns - `DeleteResponse object { id, message }` - `id: string` - `message: string` ### Example ```http curl http://localhost:5003/agents/$AGENT_ID/deployments/$DEPLOYMENT_ID \ -X DELETE \ -H "Authorization: Bearer $AGENTEX_SDK_API_KEY" ``` #### Response ```json { "id": "id", "message": "message" } ``` ## Promote Deployment **post** `/agents/{agent_id}/deployments/{deployment_id}/promote` Promote a deployment to production with atomic cutover. ### Path Parameters - `agent_id: string` - `deployment_id: string` ### Returns - `id: string` The unique identifier of the deployment. - `agent_id: string` The agent this deployment belongs to. - `docker_image: string` Full Docker image URI. - `is_production: boolean` Whether this is the production deployment. - `status: "Pending" or "Ready" or "Failed"` Current deployment status. - `"Pending"` - `"Ready"` - `"Failed"` - `acp_url: optional string` ACP URL set when agent registers. - `created_at: optional string` When the deployment was created. - `expires_at: optional string` When marked for cleanup. - `helm_release_name: optional string` Helm release name for cleanup. - `promoted_at: optional string` When promoted to production. - `registration_metadata: optional map[unknown]` Git/build metadata from the agent pod. - `sgp_deploy_id: optional string` Correlates to SGP's agentex_deploys.id. ### Example ```http curl http://localhost:5003/agents/$AGENT_ID/deployments/$DEPLOYMENT_ID/promote \ -X POST \ -H "Authorization: Bearer $AGENTEX_SDK_API_KEY" ``` #### Response ```json { "id": "id", "agent_id": "agent_id", "docker_image": "docker_image", "is_production": true, "status": "Pending", "acp_url": "acp_url", "created_at": "2019-12-27T18:11:19.117Z", "expires_at": "2019-12-27T18:11:19.117Z", "helm_release_name": "helm_release_name", "promoted_at": "2019-12-27T18:11:19.117Z", "registration_metadata": { "foo": "bar" }, "sgp_deploy_id": "sgp_deploy_id" } ``` ## Preview RPC **post** `/agents/{agent_id}/deployments/{deployment_id}/rpc` Send an RPC request to a specific deployment (for preview testing). ### Path Parameters - `agent_id: string` - `deployment_id: string` ### Body Parameters - `method: "event/send" or "task/create" or "message/send" or 2 more` - `"event/send"` - `"task/create"` - `"message/send"` - `"task/cancel"` - `"task/interrupt"` - `params: object { name, params, task_metadata } or object { task_id, task_name } or object { task_id, task_name } or 2 more` The parameters for the agent RPC request - `CreateTaskRequest object { name, params, task_metadata }` - `name: optional string` 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: optional map[unknown]` 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: optional map[unknown]` 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 object { task_id, task_name }` - `task_id: optional string` The ID of the task to cancel. Either this or task_name must be provided. - `task_name: optional string` The name of the task to cancel. Either this or task_id must be provided. - `InterruptTaskRequest object { task_id, task_name }` - `task_id: optional string` The ID of the task to interrupt. Either this or task_name must be provided. - `task_name: optional string` The name of the task to interrupt. Either this or task_id must be provided. - `SendMessageRequest object { content, stream, task_id, 2 more }` - `content: TaskMessageContent` The message that was sent to the agent - `TextContent object { author, content, attachments, 3 more }` - `author: MessageAuthor` The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. - `"user"` - `"agent"` - `content: string` The contents of the text message. - `attachments: optional array of object { file_id, name, size, type }` Optional list of file attachments with structured metadata. - `file_id: string` The unique ID of the attached file - `name: string` The name of the file - `size: number` The size of the file in bytes - `type: string` The MIME type or content type of the file - `format: optional TextFormat` The format of the message. This is used by the client to determine how to display the message. - `"markdown"` - `"plain"` - `"code"` - `style: optional MessageStyle` The style of the message. This is used by the client to determine how to display the message. - `"static"` - `"active"` - `type: optional "text"` The type of the message, in this case `text`. - `"text"` - `ReasoningContent object { author, summary, content, 2 more }` - `author: MessageAuthor` The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. - `summary: array of string` A list of short reasoning summaries - `content: optional array of string` The reasoning content or chain-of-thought text - `style: optional MessageStyle` The style of the message. This is used by the client to determine how to display the message. - `type: optional "reasoning"` The type of the message, in this case `reasoning`. - `"reasoning"` - `DataContent object { author, data, style, type }` - `author: MessageAuthor` The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. - `data: map[unknown]` The contents of the data message. - `style: optional MessageStyle` The style of the message. This is used by the client to determine how to display the message. - `type: optional "data"` The type of the message, in this case `data`. - `"data"` - `ToolRequestContent object { arguments, author, name, 3 more }` - `arguments: map[unknown]` The arguments to the tool. - `author: MessageAuthor` The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. - `name: string` The name of the tool that is being requested. - `tool_call_id: string` The ID of the tool call that is being requested. - `style: optional MessageStyle` The style of the message. This is used by the client to determine how to display the message. - `type: optional "tool_request"` The type of the message, in this case `tool_request`. - `"tool_request"` - `ToolResponseContent object { author, content, name, 4 more }` - `author: MessageAuthor` The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. - `content: unknown` The result of the tool. - `name: string` The name of the tool that is being responded to. - `tool_call_id: string` The ID of the tool call that is being responded to. - `is_error: optional boolean` Whether the tool call resulted in an error. `None` when the harness does not report a status. - `style: optional MessageStyle` The style of the message. This is used by the client to determine how to display the message. - `type: optional "tool_response"` The type of the message, in this case `tool_response`. - `"tool_response"` - `stream: optional boolean` Whether to stream the response message back to the client - `task_id: optional string` The ID of the task that the message was sent to - `task_name: optional string` The name of the task that the message was sent to - `task_params: optional map[unknown]` The parameters for the task (only used when creating new tasks) - `SendEventRequest object { content, task_id, task_name }` - `content: optional TaskMessageContent` The content to send to the event - `task_id: optional string` The ID of the task that the event was sent to - `task_name: optional string` The name of the task that the event was sent to - `id: optional number or string` - `number` - `string` - `jsonrpc: optional "2.0"` - `"2.0"` ### Returns - `AgentRpcResponse object { result, id, error, jsonrpc }` - `result: AgentRpcResult` The result of the agent RPC request - `array of TaskMessage` - `content: TaskMessageContent` The content of the message. This content is not OpenAI compatible. These are messages that are meant to be displayed to the user. - `TextContent object { author, content, attachments, 3 more }` - `author: MessageAuthor` The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. - `"user"` - `"agent"` - `content: string` The contents of the text message. - `attachments: optional array of object { file_id, name, size, type }` Optional list of file attachments with structured metadata. - `file_id: string` The unique ID of the attached file - `name: string` The name of the file - `size: number` The size of the file in bytes - `type: string` The MIME type or content type of the file - `format: optional TextFormat` The format of the message. This is used by the client to determine how to display the message. - `"markdown"` - `"plain"` - `"code"` - `style: optional MessageStyle` The style of the message. This is used by the client to determine how to display the message. - `"static"` - `"active"` - `type: optional "text"` The type of the message, in this case `text`. - `"text"` - `ReasoningContent object { author, summary, content, 2 more }` - `author: MessageAuthor` The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. - `summary: array of string` A list of short reasoning summaries - `content: optional array of string` The reasoning content or chain-of-thought text - `style: optional MessageStyle` The style of the message. This is used by the client to determine how to display the message. - `type: optional "reasoning"` The type of the message, in this case `reasoning`. - `"reasoning"` - `DataContent object { author, data, style, type }` - `author: MessageAuthor` The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. - `data: map[unknown]` The contents of the data message. - `style: optional MessageStyle` The style of the message. This is used by the client to determine how to display the message. - `type: optional "data"` The type of the message, in this case `data`. - `"data"` - `ToolRequestContent object { arguments, author, name, 3 more }` - `arguments: map[unknown]` The arguments to the tool. - `author: MessageAuthor` The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. - `name: string` The name of the tool that is being requested. - `tool_call_id: string` The ID of the tool call that is being requested. - `style: optional MessageStyle` The style of the message. This is used by the client to determine how to display the message. - `type: optional "tool_request"` The type of the message, in this case `tool_request`. - `"tool_request"` - `ToolResponseContent object { author, content, name, 4 more }` - `author: MessageAuthor` The role of the messages author, in this case `system`, `user`, `assistant`, or `tool`. - `content: unknown` The result of the tool. - `name: string` The name of the tool that is being responded to. - `tool_call_id: string` The ID of the tool call that is being responded to. - `is_error: optional boolean` Whether the tool call resulted in an error. `None` when the harness does not report a status. - `style: optional MessageStyle` The style of the message. This is used by the client to determine how to display the message. - `type: optional "tool_response"` The type of the message, in this case `tool_response`. - `"tool_response"` - `task_id: string` ID of the task this message belongs to - `id: optional string` The task message's unique id - `created_at: optional string` The timestamp when the message was created - `streaming_status: optional "IN_PROGRESS" or "DONE"` - `"IN_PROGRESS"` - `"DONE"` - `updated_at: optional string` The timestamp when the message was last updated - `StreamTaskMessageStart object { content, index, parent_task_message, type }` Event for starting a streaming message - `content: TaskMessageContent` - `index: optional number` - `parent_task_message: optional 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. - `content: TaskMessageContent` The content of the message. This content is not OpenAI compatible. These are messages that are meant to be displayed to the user. - `task_id: string` ID of the task this message belongs to - `id: optional string` The task message's unique id - `created_at: optional string` The timestamp when the message was created - `streaming_status: optional "IN_PROGRESS" or "DONE"` - `updated_at: optional string` The timestamp when the message was last updated - `type: optional "start"` - `"start"` - `StreamTaskMessageDelta object { delta, index, parent_task_message, type }` Event for streaming chunks of content - `delta: optional TaskMessageDelta` Delta for text updates - `TextDelta object { text_delta, type }` Delta for text updates - `text_delta: optional string` - `type: optional "text"` - `"text"` - `DataDelta object { data_delta, type }` Delta for data updates - `data_delta: optional string` - `type: optional "data"` - `"data"` - `ToolRequestDelta object { name, tool_call_id, arguments_delta, type }` Delta for tool request updates - `name: string` - `tool_call_id: string` - `arguments_delta: optional string` - `type: optional "tool_request"` - `"tool_request"` - `ToolResponseDelta object { name, tool_call_id, content_delta, type }` Delta for tool response updates - `name: string` - `tool_call_id: string` - `content_delta: optional string` - `type: optional "tool_response"` - `"tool_response"` - `ReasoningSummaryDelta object { summary_index, summary_delta, type }` Delta for reasoning summary updates - `summary_index: number` - `summary_delta: optional string` - `type: optional "reasoning_summary"` - `"reasoning_summary"` - `ReasoningContentDelta object { content_index, content_delta, type }` Delta for reasoning content updates - `content_index: number` - `content_delta: optional string` - `type: optional "reasoning_content"` - `"reasoning_content"` - `index: optional number` - `parent_task_message: optional 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. - `type: optional "delta"` - `"delta"` - `StreamTaskMessageFull object { content, index, parent_task_message, type }` Event for streaming the full content - `content: TaskMessageContent` - `index: optional number` - `parent_task_message: optional 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. - `type: optional "full"` - `"full"` - `StreamTaskMessageDone object { index, parent_task_message, type }` Event for indicating the task is done - `index: optional number` - `parent_task_message: optional 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. - `type: optional "done"` - `"done"` - `Task object { id, cleaned_at, created_at, 6 more }` - `id: string` - `cleaned_at: optional string` - `created_at: optional string` - `name: optional string` - `params: optional map[unknown]` - `status: optional "CANCELED" or "COMPLETED" or "FAILED" or 5 more` - `"CANCELED"` - `"COMPLETED"` - `"FAILED"` - `"RUNNING"` - `"INTERRUPTED"` - `"TERMINATED"` - `"TIMED_OUT"` - `"DELETED"` - `status_reason: optional string` - `task_metadata: optional map[unknown]` - `updated_at: optional string` - `Event object { id, agent_id, sequence_id, 3 more }` - `id: string` The UUID of the event - `agent_id: string` The UUID of the agent that the event belongs to - `sequence_id: number` The sequence ID of the event - `task_id: string` The UUID of the task that the event belongs to - `content: optional TaskMessageContent` The content of the event - `created_at: optional string` The timestamp of the event - `id: optional number or string` - `number` - `string` - `error: optional unknown` - `jsonrpc: optional "2.0"` - `"2.0"` ### Example ```http curl http://localhost:5003/agents/$AGENT_ID/deployments/$DEPLOYMENT_ID/rpc \ -H 'Content-Type: application/json' \ -H "Authorization: Bearer $AGENTEX_SDK_API_KEY" \ -d '{ "method": "event/send", "params": {} }' ``` #### Response ```json { "result": [ { "content": { "author": "user", "content": "content", "attachments": [ { "file_id": "file_id", "name": "name", "size": 0, "type": "type" } ], "format": "markdown", "style": "static", "type": "text" }, "task_id": "task_id", "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "streaming_status": "IN_PROGRESS", "updated_at": "2019-12-27T18:11:19.117Z" } ], "id": 0, "error": {}, "jsonrpc": "2.0" } ``` ## Domain Types ### Deployment Create Response - `DeploymentCreateResponse object { id, agent_id, docker_image, 9 more }` - `id: string` The unique identifier of the deployment. - `agent_id: string` The agent this deployment belongs to. - `docker_image: string` Full Docker image URI. - `is_production: boolean` Whether this is the production deployment. - `status: "Pending" or "Ready" or "Failed"` Current deployment status. - `"Pending"` - `"Ready"` - `"Failed"` - `acp_url: optional string` ACP URL set when agent registers. - `created_at: optional string` When the deployment was created. - `expires_at: optional string` When marked for cleanup. - `helm_release_name: optional string` Helm release name for cleanup. - `promoted_at: optional string` When promoted to production. - `registration_metadata: optional map[unknown]` Git/build metadata from the agent pod. - `sgp_deploy_id: optional string` Correlates to SGP's agentex_deploys.id. ### Deployment List Response - `DeploymentListResponse = array of object { id, agent_id, docker_image, 9 more }` - `id: string` The unique identifier of the deployment. - `agent_id: string` The agent this deployment belongs to. - `docker_image: string` Full Docker image URI. - `is_production: boolean` Whether this is the production deployment. - `status: "Pending" or "Ready" or "Failed"` Current deployment status. - `"Pending"` - `"Ready"` - `"Failed"` - `acp_url: optional string` ACP URL set when agent registers. - `created_at: optional string` When the deployment was created. - `expires_at: optional string` When marked for cleanup. - `helm_release_name: optional string` Helm release name for cleanup. - `promoted_at: optional string` When promoted to production. - `registration_metadata: optional map[unknown]` Git/build metadata from the agent pod. - `sgp_deploy_id: optional string` Correlates to SGP's agentex_deploys.id. ### Deployment Retrieve Response - `DeploymentRetrieveResponse object { id, agent_id, docker_image, 9 more }` - `id: string` The unique identifier of the deployment. - `agent_id: string` The agent this deployment belongs to. - `docker_image: string` Full Docker image URI. - `is_production: boolean` Whether this is the production deployment. - `status: "Pending" or "Ready" or "Failed"` Current deployment status. - `"Pending"` - `"Ready"` - `"Failed"` - `acp_url: optional string` ACP URL set when agent registers. - `created_at: optional string` When the deployment was created. - `expires_at: optional string` When marked for cleanup. - `helm_release_name: optional string` Helm release name for cleanup. - `promoted_at: optional string` When promoted to production. - `registration_metadata: optional map[unknown]` Git/build metadata from the agent pod. - `sgp_deploy_id: optional string` Correlates to SGP's agentex_deploys.id. ### Deployment Promote Response - `DeploymentPromoteResponse object { id, agent_id, docker_image, 9 more }` - `id: string` The unique identifier of the deployment. - `agent_id: string` The agent this deployment belongs to. - `docker_image: string` Full Docker image URI. - `is_production: boolean` Whether this is the production deployment. - `status: "Pending" or "Ready" or "Failed"` Current deployment status. - `"Pending"` - `"Ready"` - `"Failed"` - `acp_url: optional string` ACP URL set when agent registers. - `created_at: optional string` When the deployment was created. - `expires_at: optional string` When marked for cleanup. - `helm_release_name: optional string` Helm release name for cleanup. - `promoted_at: optional string` When promoted to production. - `registration_metadata: optional map[unknown]` Git/build metadata from the agent pod. - `sgp_deploy_id: optional string` Correlates to SGP's agentex_deploys.id.