> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# ai agent
> Create, manage, and interact with AI agents and their conversations
**Server path:** `/agent-management` | **Type:** Embedded | **PCID required:** No
## Tools
| Tool | Description |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`agent_create`](#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_update`](#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}. |
| [`agent_read`](#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_invoke`](#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. |
| [`agent_list`](#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. |
| [`chat_create`](#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`](#chat_list) | List all 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. |
| [`chat_reset_conversation`](#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. |
| [`chat_list_artifacts`](#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. |
| [`agent_publish_release`](#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_toggle_public_template`](#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\_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](mailto: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: "\" \
- 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")) |
```json theme={null}
{
"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\" ' — 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: \"\" \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"
],
"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\_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](mailto: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: "\" \
- 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. |
```json theme={null}
{
"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\" ' — 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: \"\" \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"
],
"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"
]
}
```
***
## 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. |
```json theme={null}
{
"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\_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.
**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. |
| `mode` | string | No | — | Optional agent mode for routing. "action\_agent" routes to GPT-based agent (default), "claude\_agent" routes to Claude-based agent. |
| `messagesInResponse` | boolean | No | — | If true, includes the full message history in the response. Useful for debugging or reviewing conversation context. |
```json theme={null}
{
"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."
},
"mode": {
"type": "string",
"enum": [
"action_agent",
"claude_agent"
],
"description": "Optional agent mode for routing. \"action_agent\" routes to GPT-based agent (default), \"claude_agent\" routes to Claude-based agent."
},
"messagesInResponse": {
"type": "boolean",
"description": "If true, includes the full message history in the response. Useful for debugging or reviewing conversation context."
}
},
"required": [
"agentId",
"message"
]
}
```
***
## 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:** None
```json theme={null}
{
"type": "object",
"properties": {}
}
```
***
## 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 \". |
```json theme={null}
{
"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 \"."
}
},
"required": [
"agentId"
]
}
```
***
## chat\_list
List all 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.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ------------------------------------- |
| `agentId` | string | Yes | — | Agent ID to list chats for. Required. |
```json theme={null}
{
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "Agent ID to list chats for. Required."
}
},
"required": [
"agentId"
]
}
```
***
## 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. |
```json theme={null}
{
"type": "object",
"properties": {
"chatId": {
"type": "string",
"description": "ID of the chat whose conversation history should be reset."
}
},
"required": [
"chatId"
]
}
```
***
## 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. |
```json theme={null}
{
"type": "object",
"properties": {
"chatId": {
"type": "string",
"description": "ID of the chat to list artifacts for."
}
},
"required": [
"chatId"
]
}
```
***
## 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") |
```json theme={null}
{
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "ID of the agent to publish a release for (e.g. \"ua_abc123\")"
}
},
"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. |
```json theme={null}
{
"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"
]
}
```