/agent-management | Type: Embedded | PCID required: No
Tools
| Tool | Description |
|---|---|
agent_create | Create a new agent with specified configuration including name, description, instructions, tools, and resources. Two ways to add server tools: (1) Add all tools from a server: {“name”: “github”, “allTools”: true} — no need to list individual tools. (2) Add specific tools: call capabilities_discover to find relevant servers/tools, then list them in the tools field. Returns the created agent with its ID. |
agent_invoke | Invoke an agent and get its response. Use this to leverage agent capabilities for data processing, decision making, or complex tasks. The agent can be invoked with a message and optionally continue a conversation using chatId. Returns the agent’s response, chatId for continuing conversations, and agentId. Waits for the agent and returns inline; if a run exceeds ~50s it does not block or error — it returns an operationId to poll with agent_invoke_status. Pass async: true to get that operationId immediately without waiting. |
agent_invoke_status | Check the status (and retrieve the result) of an agent invoked in fire-and-return mode (agent_invoke with async: true). Pass the operationId that invoke returned. Returns status RUNNING until the agent finishes, then COMPLETE with the response (or FAILED with an error). Poll at a modest interval (~5-10s). You can only read operations you started. |
agent_list | List all agents accessible to the current user. Returns a summary of each agent including its ID, name, and description. Use this to discover available agents before invoking or updating them. |
agent_publish_release | Publish a release for an agent, locking in its current configuration as a versioned snapshot. A release is required before an agent can be made available as a public template. If nothing has changed since the last release, returns a message indicating nothing to release. |
agent_read | Get detailed information about an agent including its configuration, tools, resources, and permissions. Use this to inspect an agent before updating it or to understand its capabilities. |
agent_toggle_public_template | Toggle whether an agent is available as a public template in the template gallery. When enabling (available=true), the agent must have at least one published release. Provide a category and optional tags. When disabling (available=false), the agent is removed from the public gallery. Use agent_publish_release first to create a release before enabling. |
agent_update | Update an existing agent. Only provided fields will be updated - other fields remain unchanged. Requires the agent ID from create or read operations. Two ways to add server tools: (1) All tools from a server: {“name”: “github”, “allTools”: true}. (2) Specific tools: call capabilities_discover to find relevant servers/tools, then list them. Example: If user says “add all github tools”, use {“name”: “github”, “allTools”: true}. |
chat_create | Create a new chat session for an agent. A chat provides a persistent conversation context that maintains message history across multiple agent_invoke calls. After creating a chat, use agent_invoke with the returned chatId to send messages within this conversation. |
chat_list | List chat sessions for a specific agent. Returns chat metadata including ID, name, agent association, and creation date. Use this to find existing conversations to resume via agent_invoke. Pagination is opt-in: omit limit and cursor to receive every chat for the agent (default behavior); supply limit and/or cursor to page through results, then pass the returned nextCursor back in as cursor to fetch the next page (hasMore indicates more remain). |
chat_list_artifacts | List all artifacts associated with a chat. Returns artifact metadata including IDs, names, MIME types, sizes, and download URLs. Artifacts are created by agents during code execution (via createArtifact) or uploaded by users. |
chat_reset_conversation | Reset a chat’s conversation history, clearing all messages. The chat itself is preserved but its message history is wiped clean. Use this to start a fresh conversation within an existing chat session. The next agent_invoke call with this chatId will behave as if the conversation just started. |
agent_create
Create a new agent with specified configuration including name, description, instructions, tools, and resources. Two ways to add server tools: (1) Add all tools from a server: {“name”: “github”, “allTools”: true} — no need to list individual tools. (2) Add specific tools: call capabilities_discover to find relevant servers/tools, then list them in the tools field. Returns the created agent with its ID. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Display name for the agent |
description | string | Yes | — | Description of what the agent does |
instructions | string | Yes | — | System instructions/prompt for the agent — guides behavior and capabilities. Available platform-injected context variables you can reference by name: currentAutomationId (id of the current chat); chatReplyAddress (RFC 5322 Reply-To value, e.g. ‘“Hiring Manager” <abc123+ua_xyz@dev30.pinkfishdev.email>’ — pass verbatim to the email/gmail tool so replies thread back to this chat); chatReplyEmail (bare email, no display name — prefer chatReplyAddress). When the agent will send emails recipients are expected to reply to, include this block in the instructions verbatim:Email Communication: When sending emails: - Always set the reply-to address to chatReplyAddress, ensuring it follows the format: “<Your Agent Name>” <emailAddress> - This displays your agent name as the sender and ensures user replies reach you directly in this chat - Maintain email threading by using the messageId from incoming emails in the In-Reply-To header when responding - Always include the original messageId in the references when continuing a conversation thread - This keeps conversations organized and threaded properly Without that block, replies route to the wrong inbox / get orphaned from the chat. |
outputSchema | string | No | — | Optional JSON schema for agent output structure |
promptExamples | string[] | No | [] | Example prompts shown as suggestion bubbles in the chat UI. These help users understand what the agent can do. Example: [“Analyze this RFP”, “Draft a response for this opportunity”] |
selectedModel | string | No | — | LLM model for the agent. If omitted, defaults to sonnet. |
introMessage | string | No | — | Welcome message shown when a user opens the agent chat for the first time. |
servers | any | No | [] | MCP servers and tools to grant the agent access to. Two options per server: (1) All tools: {“name”: “github”, “allTools”: true} — includes every tool from the server. (2) Specific tools: {“name”: “google-drive”, “tools”: {“google-drive_list_files”: {}}} — call capabilities_discover to find relevant servers/tools first. Examples: [{“name”: “github”, “allTools”: true}, {“name”: “slack”, “tools”: {“slack_send_message”: {}}}]. For agents without any tool access, use empty array: [] |
resources | any[] | No | [] | Generic resources configuration (advanced use) |
datastores | object[] | No | [] | NOT YET SUPPORTED. Granting datastore access during agent creation is not yet implemented. Do NOT use this field - inform the user this feature is coming soon. |
filestores | object[] | No | [] | NOT YET SUPPORTED. Granting filestore access during agent creation is not yet implemented. Do NOT use this field - inform the user this feature is coming soon. |
knowledgeBases | object[] | No | [] | NOT YET SUPPORTED. Granting knowledge base access during agent creation is not yet implemented. Do NOT use this field - inform the user this feature is coming soon. |
workflows | object[] | No | [] | Workflows the agent can trigger |
verificationPlanConfig | any | No | — | Optional process definition that turns this agent into a gated workflow (PIN-5480). The plan is a VerificationPlanDefinition: an ordered list of phases, each with a checklist of items (kind: task | document | boolean | choice | system_check | agent_verification | human_approval). Phases advance only when required items are satisfied. agent_update REPLACES the plan — always agent_read first and send the merged plan. Omit this field to leave the plan unchanged. |
bindToWorkflow | object | No | — | Optionally bind this agent to a workflow immediately after creation. Agent will be available as a resource in the workflow for calling via config.callAgent(config.getAgent(“resourceName”)) |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Display name for the agent"
},
"description": {
"type": "string",
"description": "Description of what the agent does"
},
"instructions": {
"type": "string",
"description": "System instructions/prompt for the agent — guides behavior and capabilities. Available platform-injected context variables you can reference by name: `currentAutomationId` (id of the current chat); `chatReplyAddress` (RFC 5322 Reply-To value, e.g. '\"Hiring Manager\" <abc123+ua_xyz@dev30.pinkfishdev.email>' — pass verbatim to the email/gmail tool so replies thread back to this chat); `chatReplyEmail` (bare email, no display name — prefer chatReplyAddress). When the agent will send emails recipients are expected to reply to, include this block in the instructions verbatim:\n\n**Email Communication:** When sending emails:\n- Always set the reply-to address to chatReplyAddress, ensuring it follows the format: \"<Your Agent Name>\" <emailAddress>\n- This displays your agent name as the sender and ensures user replies reach you directly in this chat\n- Maintain email threading by using the messageId from incoming emails in the In-Reply-To header when responding\n- Always include the original messageId in the references when continuing a conversation thread\n- This keeps conversations organized and threaded properly\n\nWithout that block, replies route to the wrong inbox / get orphaned from the chat."
},
"outputSchema": {
"type": "string",
"description": "Optional JSON schema for agent output structure"
},
"promptExamples": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Example prompts shown as suggestion bubbles in the chat UI. These help users understand what the agent can do. Example: [\"Analyze this RFP\", \"Draft a response for this opportunity\"]"
},
"selectedModel": {
"type": "string",
"enum": [
"haiku",
"sonnet",
"opus-low",
"opus-medium",
"opus-high",
"mercury-2",
"gpt-5.4",
"gpt-5-mini",
"gpt-5-nano",
"groq-gpt-oss-120b",
"groq-gpt-oss-20b",
"fireworks-kimi-k2p5",
"fireworks-kimi-k2p6"
],
"description": "LLM model for the agent. If omitted, defaults to sonnet."
},
"introMessage": {
"type": "string",
"description": "Welcome message shown when a user opens the agent chat for the first time."
},
"servers": {
"type": "effects",
"default": [],
"description": "MCP servers and tools to grant the agent access to. Two options per server: (1) All tools: {\"name\": \"github\", \"allTools\": true} — includes every tool from the server. (2) Specific tools: {\"name\": \"google-drive\", \"tools\": {\"google-drive_list_files\": {}}} — call capabilities_discover to find relevant servers/tools first. Examples: [{\"name\": \"github\", \"allTools\": true}, {\"name\": \"slack\", \"tools\": {\"slack_send_message\": {}}}]. For agents without any tool access, use empty array: []"
},
"resources": {
"type": "array",
"items": {
"type": "unknown"
},
"default": [],
"description": "Generic resources configuration (advanced use)"
},
"datastores": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Collection ID"
},
"name": {
"type": "string",
"description": "Collection name"
},
"description": {
"type": "string",
"description": "Collection description"
},
"canRead": {
"type": "boolean",
"description": "Whether the agent can read from this collection"
},
"canWrite": {
"type": "boolean",
"description": "Whether the agent can write to this collection"
},
"canDelete": {
"type": "boolean",
"description": "Whether the agent can delete from this collection"
},
"proxyEndpointId": {
"type": "string",
"description": "Proxy endpoint ID for accessing this collection"
}
}
},
"default": [],
"description": "NOT YET SUPPORTED. Granting datastore access during agent creation is not yet implemented. Do NOT use this field - inform the user this feature is coming soon."
},
"filestores": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Collection ID"
},
"name": {
"type": "string",
"description": "Collection name"
},
"description": {
"type": "string",
"description": "Collection description"
},
"canRead": {
"type": "boolean",
"description": "Whether the agent can read from this collection"
},
"canWrite": {
"type": "boolean",
"description": "Whether the agent can write to this collection"
},
"canDelete": {
"type": "boolean",
"description": "Whether the agent can delete from this collection"
},
"proxyEndpointId": {
"type": "string",
"description": "Proxy endpoint ID for accessing this collection"
}
}
},
"default": [],
"description": "NOT YET SUPPORTED. Granting filestore access during agent creation is not yet implemented. Do NOT use this field - inform the user this feature is coming soon."
},
"knowledgeBases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Collection ID"
},
"name": {
"type": "string",
"description": "Collection name"
},
"description": {
"type": "string",
"description": "Collection description"
},
"canRead": {
"type": "boolean",
"description": "Whether the agent can read from this collection"
},
"canWrite": {
"type": "boolean",
"description": "Whether the agent can write to this collection"
},
"canDelete": {
"type": "boolean",
"description": "Whether the agent can delete from this collection"
},
"proxyEndpointId": {
"type": "string",
"description": "Proxy endpoint ID for accessing this collection"
}
}
},
"default": [],
"description": "NOT YET SUPPORTED. Granting knowledge base access during agent creation is not yet implemented. Do NOT use this field - inform the user this feature is coming soon."
},
"workflows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"triggerName": {
"type": "string",
"description": "Name of the workflow trigger"
},
"workflowName": {
"type": "string",
"description": "Name of the workflow"
},
"triggerUrl": {
"type": "string",
"description": "URL to trigger the workflow"
},
"triggerApiKey": {
"type": "string",
"description": "API key for triggering the workflow"
},
"toolName": {
"type": "string",
"description": "Optional tool name for the workflow"
}
}
},
"default": [],
"description": "Workflows the agent can trigger"
},
"verificationPlanConfig": {
"type": "effects",
"description": "Optional process definition that turns this agent into a gated workflow (PIN-5480). The plan is a VerificationPlanDefinition: an ordered list of phases, each with a checklist of items (kind: task | document | boolean | choice | system_check | agent_verification | human_approval). Phases advance only when required items are satisfied. agent_update REPLACES the plan — always agent_read first and send the merged plan. Omit this field to leave the plan unchanged."
},
"bindToWorkflow": {
"type": "object",
"properties": {
"automationId": {
"type": "string",
"description": "Workflow automation ID to bind this agent to"
},
"resourceName": {
"type": "string",
"description": "Resource name in WORKFLOW_RESOURCES to bind agent to (e.g., \"contentWriter\")"
}
},
"description": "Optionally bind this agent to a workflow immediately after creation. Agent will be available as a resource in the workflow for calling via config.callAgent(config.getAgent(\"resourceName\"))"
}
},
"required": [
"name",
"description",
"instructions"
]
}
agent_invoke
Invoke an agent and get its response. Use this to leverage agent capabilities for data processing, decision making, or complex tasks. The agent can be invoked with a message and optionally continue a conversation using chatId. Returns the agent’s response, chatId for continuing conversations, and agentId. Waits for the agent and returns inline; if a run exceeds ~50s it does not block or error — it returns an operationId to poll with agent_invoke_status. Pass async: true to get that operationId immediately without waiting. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
agentId | string | Yes | — | ID of the agent to invoke. Use agent_read or workflow_agents to see available agents. |
message | string | Yes | — | The message or task to send to the agent. Be clear and specific about what you need the agent to do. |
chatId | string | No | — | Optional chat ID to continue a previous conversation. If provided, the conversation history will be loaded. If omitted, a new conversation will be started. |
messagesInResponse | boolean | No | — | If true, adds a messages array to the response containing the conversation history. Each entry carries role, content, and a sequence — a chat-scoped message identifier. Address a message as (chatId, sequence): sequence is NOT globally unique and repeats across chats. Sequences increase but are GAPPED, not contiguous — deleted messages and tool-call/status messages keep their numbers but are filtered out of this array, so a chat with tool calls returns e.g. 1, 2, 5, 9, and the first entry is not necessarily 1. Conversations served from the legacy history path carry no sequence at all. Current conversations are capped at the 250 most recent messages and longer ones are silently truncated; legacy-path conversations are returned in full. There is no pagination for messages and no separate history endpoint — this flag returns the whole array on every call, so request it only when you need the history. |
async | boolean | No | — | Fire-and-return mode (PIN-8288). When true, returns an operationId immediately without waiting for the agent to finish; poll agent_invoke_status with that operationId until COMPLETE. Default false (waits and returns the response, as today). |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "ID of the agent to invoke. Use agent_read or workflow_agents to see available agents."
},
"message": {
"type": "string",
"description": "The message or task to send to the agent. Be clear and specific about what you need the agent to do."
},
"chatId": {
"type": "string",
"description": "Optional chat ID to continue a previous conversation. If provided, the conversation history will be loaded. If omitted, a new conversation will be started."
},
"messagesInResponse": {
"type": "boolean",
"description": "If true, adds a `messages` array to the response containing the conversation history. Each entry carries `role`, `content`, and a `sequence` — a chat-scoped message identifier. Address a message as (chatId, sequence): sequence is NOT globally unique and repeats across chats. Sequences increase but are GAPPED, not contiguous — deleted messages and tool-call/status messages keep their numbers but are filtered out of this array, so a chat with tool calls returns e.g. 1, 2, 5, 9, and the first entry is not necessarily 1. Conversations served from the legacy history path carry no `sequence` at all. Current conversations are capped at the 250 most recent messages and longer ones are silently truncated; legacy-path conversations are returned in full. There is no pagination for messages and no separate history endpoint — this flag returns the whole array on every call, so request it only when you need the history."
},
"async": {
"type": "boolean",
"description": "Fire-and-return mode (PIN-8288). When true, returns an operationId immediately without waiting for the agent to finish; poll agent_invoke_status with that operationId until COMPLETE. Default false (waits and returns the response, as today)."
}
},
"required": [
"agentId",
"message"
]
}
agent_invoke_status
Check the status (and retrieve the result) of an agent invoked in fire-and-return mode (agent_invoke with async: true). Pass the operationId that invoke returned. Returns status RUNNING until the agent finishes, then COMPLETE with the response (or FAILED with an error). Poll at a modest interval (~5-10s). You can only read operations you started. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
operationId | string | Yes | — | The operationId returned by agent_invoke when called with async: true. |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"description": "The operationId returned by agent_invoke when called with async: true."
}
},
"required": [
"operationId"
]
}
agent_list
List all agents accessible to the current user. Returns a summary of each agent including its ID, name, and description. Use this to discover available agents before invoking or updating them. Parameters: NoneShow inputSchema
Show inputSchema
{
"type": "object",
"properties": {}
}
agent_publish_release
Publish a release for an agent, locking in its current configuration as a versioned snapshot. A release is required before an agent can be made available as a public template. If nothing has changed since the last release, returns a message indicating nothing to release. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
agentId | string | Yes | — | ID of the agent to publish a release for (e.g. “ua_abc123”) |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "ID of the agent to publish a release for (e.g. \"ua_abc123\")"
}
},
"required": [
"agentId"
]
}
agent_read
Get detailed information about an agent including its configuration, tools, resources, and permissions. Use this to inspect an agent before updating it or to understand its capabilities. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
agentId | string | Yes | — | ID of the agent to retrieve (e.g. “ua_abc123”). Use this exact ID from create operation or from listing agents. |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "ID of the agent to retrieve (e.g. \"ua_abc123\"). Use this exact ID from create operation or from listing agents."
}
},
"required": [
"agentId"
]
}
agent_toggle_public_template
Toggle whether an agent is available as a public template in the template gallery. When enabling (available=true), the agent must have at least one published release. Provide a category and optional tags. When disabling (available=false), the agent is removed from the public gallery. Use agent_publish_release first to create a release before enabling. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
agentId | string | Yes | — | ID of the agent to toggle template availability for |
available | boolean | Yes | — | true to make the agent available as a public template, false to remove it from the gallery |
category | string | No | — | Template category (e.g. “sales”, “productivity”, “engineering”). Required when available=true. |
publicTags | string[] | No | — | Up to 3 tags for the template (e.g. [“crm”, “analytics”]). Optional, only used when available=true. Tags are lowercased automatically. |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "ID of the agent to toggle template availability for"
},
"available": {
"type": "boolean",
"description": "true to make the agent available as a public template, false to remove it from the gallery"
},
"category": {
"type": "string",
"description": "Template category (e.g. \"sales\", \"productivity\", \"engineering\"). Required when available=true."
},
"publicTags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to 3 tags for the template (e.g. [\"crm\", \"analytics\"]). Optional, only used when available=true. Tags are lowercased automatically."
}
},
"required": [
"agentId",
"available"
]
}
agent_update
Update an existing agent. Only provided fields will be updated - other fields remain unchanged. Requires the agent ID from create or read operations. Two ways to add server tools: (1) All tools from a server: {“name”: “github”, “allTools”: true}. (2) Specific tools: call capabilities_discover to find relevant servers/tools, then list them. Example: If user says “add all github tools”, use {“name”: “github”, “allTools”: true}. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
agentId | string | Yes | — | ID of the agent to update (e.g. “ua_abc123”) |
name | string | No | — | Updated display name for the agent |
description | string | No | — | Updated description of what the agent does |
instructions | string | No | — | Updated System instructions/prompt for the agent — guides behavior and capabilities. Available platform-injected context variables you can reference by name: currentAutomationId (id of the current chat); chatReplyAddress (RFC 5322 Reply-To value, e.g. ‘“Hiring Manager” <abc123+ua_xyz@dev30.pinkfishdev.email>’ — pass verbatim to the email/gmail tool so replies thread back to this chat); chatReplyEmail (bare email, no display name — prefer chatReplyAddress). When the agent will send emails recipients are expected to reply to, include this block in the instructions verbatim:Email Communication: When sending emails: - Always set the reply-to address to chatReplyAddress, ensuring it follows the format: “<Your Agent Name>” <emailAddress> - This displays your agent name as the sender and ensures user replies reach you directly in this chat - Maintain email threading by using the messageId from incoming emails in the In-Reply-To header when responding - Always include the original messageId in the references when continuing a conversation thread - This keeps conversations organized and threaded properly Without that block, replies route to the wrong inbox / get orphaned from the chat. |
outputSchema | string | No | — | Updated JSON schema for agent output structure |
promptExamples | string[] | No | — | Updated example prompts shown as suggestion bubbles in the chat UI. |
selectedModel | string | No | — | Updated LLM model for the agent. |
introMessage | string | No | — | Updated welcome message shown when a user opens the agent chat. |
servers | any | No | — | Updated MCP servers and tools configuration. If provided, replaces existing servers completely. Use {“name”: “server”, “allTools”: true} to add all tools from a server, or call capabilities_discover to find specific tools. Example: [{“name”: “github”, “allTools”: true}, {“name”: “slack”, “tools”: {“slack_send_message”: {}}}] |
resources | any[] | No | — | Updated generic resources configuration |
datastores | object[] | No | — | NOT YET SUPPORTED. Granting datastore access is not yet implemented. Do NOT use this field - inform the user this feature is coming soon. |
filestores | object[] | No | — | NOT YET SUPPORTED. Granting filestore access is not yet implemented. Do NOT use this field - inform the user this feature is coming soon. |
knowledgeBases | object[] | No | — | NOT YET SUPPORTED. Granting knowledge base access is not yet implemented. Do NOT use this field - inform the user this feature is coming soon. |
workflows | object[] | No | — | Updated workflows configuration |
verificationPlanConfig | any | No | — | Optional process definition that turns this agent into a gated workflow (PIN-5480). The plan is a VerificationPlanDefinition: an ordered list of phases, each with a checklist of items (kind: task | document | boolean | choice | system_check | agent_verification | human_approval). Phases advance only when required items are satisfied. agent_update REPLACES the plan — always agent_read first and send the merged plan. Omit this field to leave the plan unchanged. Pass null to clear the plan entirely. |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "ID of the agent to update (e.g. \"ua_abc123\")"
},
"name": {
"type": "string",
"description": "Updated display name for the agent"
},
"description": {
"type": "string",
"description": "Updated description of what the agent does"
},
"instructions": {
"type": "string",
"description": "Updated System instructions/prompt for the agent — guides behavior and capabilities. Available platform-injected context variables you can reference by name: `currentAutomationId` (id of the current chat); `chatReplyAddress` (RFC 5322 Reply-To value, e.g. '\"Hiring Manager\" <abc123+ua_xyz@dev30.pinkfishdev.email>' — pass verbatim to the email/gmail tool so replies thread back to this chat); `chatReplyEmail` (bare email, no display name — prefer chatReplyAddress). When the agent will send emails recipients are expected to reply to, include this block in the instructions verbatim:\n\n**Email Communication:** When sending emails:\n- Always set the reply-to address to chatReplyAddress, ensuring it follows the format: \"<Your Agent Name>\" <emailAddress>\n- This displays your agent name as the sender and ensures user replies reach you directly in this chat\n- Maintain email threading by using the messageId from incoming emails in the In-Reply-To header when responding\n- Always include the original messageId in the references when continuing a conversation thread\n- This keeps conversations organized and threaded properly\n\nWithout that block, replies route to the wrong inbox / get orphaned from the chat."
},
"outputSchema": {
"type": "string",
"description": "Updated JSON schema for agent output structure"
},
"promptExamples": {
"type": "array",
"items": {
"type": "string"
},
"description": "Updated example prompts shown as suggestion bubbles in the chat UI."
},
"selectedModel": {
"type": "string",
"enum": [
"haiku",
"sonnet",
"opus-low",
"opus-medium",
"opus-high",
"mercury-2",
"gpt-5.4",
"gpt-5-mini",
"gpt-5-nano",
"groq-gpt-oss-120b",
"groq-gpt-oss-20b",
"fireworks-kimi-k2p5",
"fireworks-kimi-k2p6"
],
"description": "Updated LLM model for the agent."
},
"introMessage": {
"type": "string",
"description": "Updated welcome message shown when a user opens the agent chat."
},
"servers": {
"type": "effects",
"description": "Updated MCP servers and tools configuration. If provided, replaces existing servers completely. Use {\"name\": \"server\", \"allTools\": true} to add all tools from a server, or call capabilities_discover to find specific tools. Example: [{\"name\": \"github\", \"allTools\": true}, {\"name\": \"slack\", \"tools\": {\"slack_send_message\": {}}}]"
},
"resources": {
"type": "array",
"items": {
"type": "unknown"
},
"description": "Updated generic resources configuration"
},
"datastores": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Collection ID"
},
"name": {
"type": "string",
"description": "Collection name"
},
"description": {
"type": "string",
"description": "Collection description"
},
"canRead": {
"type": "boolean",
"description": "Whether the agent can read from this collection"
},
"canWrite": {
"type": "boolean",
"description": "Whether the agent can write to this collection"
},
"canDelete": {
"type": "boolean",
"description": "Whether the agent can delete from this collection"
},
"proxyEndpointId": {
"type": "string",
"description": "Proxy endpoint ID for accessing this collection"
}
}
},
"description": "NOT YET SUPPORTED. Granting datastore access is not yet implemented. Do NOT use this field - inform the user this feature is coming soon."
},
"filestores": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Collection ID"
},
"name": {
"type": "string",
"description": "Collection name"
},
"description": {
"type": "string",
"description": "Collection description"
},
"canRead": {
"type": "boolean",
"description": "Whether the agent can read from this collection"
},
"canWrite": {
"type": "boolean",
"description": "Whether the agent can write to this collection"
},
"canDelete": {
"type": "boolean",
"description": "Whether the agent can delete from this collection"
},
"proxyEndpointId": {
"type": "string",
"description": "Proxy endpoint ID for accessing this collection"
}
}
},
"description": "NOT YET SUPPORTED. Granting filestore access is not yet implemented. Do NOT use this field - inform the user this feature is coming soon."
},
"knowledgeBases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Collection ID"
},
"name": {
"type": "string",
"description": "Collection name"
},
"description": {
"type": "string",
"description": "Collection description"
},
"canRead": {
"type": "boolean",
"description": "Whether the agent can read from this collection"
},
"canWrite": {
"type": "boolean",
"description": "Whether the agent can write to this collection"
},
"canDelete": {
"type": "boolean",
"description": "Whether the agent can delete from this collection"
},
"proxyEndpointId": {
"type": "string",
"description": "Proxy endpoint ID for accessing this collection"
}
}
},
"description": "NOT YET SUPPORTED. Granting knowledge base access is not yet implemented. Do NOT use this field - inform the user this feature is coming soon."
},
"workflows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"triggerName": {
"type": "string",
"description": "Name of the workflow trigger"
},
"workflowName": {
"type": "string",
"description": "Name of the workflow"
},
"triggerUrl": {
"type": "string",
"description": "URL to trigger the workflow"
},
"triggerApiKey": {
"type": "string",
"description": "API key for triggering the workflow"
},
"toolName": {
"type": "string",
"description": "Optional tool name for the workflow"
}
}
},
"description": "Updated workflows configuration"
},
"verificationPlanConfig": {
"type": "effects",
"nullable": true,
"description": "Optional process definition that turns this agent into a gated workflow (PIN-5480). The plan is a VerificationPlanDefinition: an ordered list of phases, each with a checklist of items (kind: task | document | boolean | choice | system_check | agent_verification | human_approval). Phases advance only when required items are satisfied. agent_update REPLACES the plan — always agent_read first and send the merged plan. Omit this field to leave the plan unchanged. Pass null to clear the plan entirely."
}
},
"required": [
"agentId"
]
}
chat_create
Create a new chat session for an agent. A chat provides a persistent conversation context that maintains message history across multiple agent_invoke calls. After creating a chat, use agent_invoke with the returned chatId to send messages within this conversation. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
agentId | string | Yes | — | ID of the agent to create a chat for (e.g. “ua_abc123”). The agent must already exist. |
name | string | No | — | Optional display name for the chat. If omitted, defaults to “Chat with agent <agentId>“. |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "ID of the agent to create a chat for (e.g. \"ua_abc123\"). The agent must already exist."
},
"name": {
"type": "string",
"description": "Optional display name for the chat. If omitted, defaults to \"Chat with agent <agentId>\"."
}
},
"required": [
"agentId"
]
}
chat_list
List chat sessions for a specific agent. Returns chat metadata including ID, name, agent association, and creation date. Use this to find existing conversations to resume via agent_invoke. Pagination is opt-in: omit limit and cursor to receive every chat for the agent (default behavior); supply limit and/or cursor to page through results, then pass the returned nextCursor back in as cursor to fetch the next page (hasMore indicates more remain). Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
agentId | string | Yes | — | Agent ID to list chats for. Required. |
limit | number | No | — | Optional. Maximum number of chats to return for this page (1-500). When omitted and no cursor is supplied, all chats are returned. When a cursor is supplied without a limit, a default page size of 50 is used. |
cursor | string | No | — | Optional. Opaque pagination cursor from a previous response nextCursor. Supplying it returns the next page of chats. |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "Agent ID to list chats for. Required."
},
"limit": {
"type": "number",
"description": "Optional. Maximum number of chats to return for this page (1-500). When omitted and no cursor is supplied, all chats are returned. When a cursor is supplied without a limit, a default page size of 50 is used."
},
"cursor": {
"type": "string",
"description": "Optional. Opaque pagination cursor from a previous response nextCursor. Supplying it returns the next page of chats."
}
},
"required": [
"agentId"
]
}
chat_list_artifacts
List all artifacts associated with a chat. Returns artifact metadata including IDs, names, MIME types, sizes, and download URLs. Artifacts are created by agents during code execution (via createArtifact) or uploaded by users. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
chatId | string | Yes | — | ID of the chat to list artifacts for. |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"chatId": {
"type": "string",
"description": "ID of the chat to list artifacts for."
}
},
"required": [
"chatId"
]
}
chat_reset_conversation
Reset a chat’s conversation history, clearing all messages. The chat itself is preserved but its message history is wiped clean. Use this to start a fresh conversation within an existing chat session. The next agent_invoke call with this chatId will behave as if the conversation just started. Parameters:| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
chatId | string | Yes | — | ID of the chat whose conversation history should be reset. |
Show inputSchema
Show inputSchema
{
"type": "object",
"properties": {
"chatId": {
"type": "string",
"description": "ID of the chat whose conversation history should be reset."
}
},
"required": [
"chatId"
]
}