Skip to main content
Server path: /agent-management | Type: Embedded | PCID required: No Create agents, start conversations, and retrieve artifacts. For a guided walkthrough, see the Agent Management guide.

​
Tools

ToolDescription
agent_createCreate a new agent with instructions and tool access
agent_listList all accessible agents
agent_readGet full agent configuration and metadata
agent_updateUpdate agent fields (partial update)
agent_invokeSend a message to an agent and get a response
chat_createCreate a chat session for an agent
chat_listList chat sessions, optionally filtered by agent
chat_reset_conversationClear conversation history in a chat
chat_list_artifactsList artifacts (files) in a chat

​
agent_create

Create a new agent with instructions, tool access, and optional workflow bindings. Parameters:
ParameterTypeRequiredDescription
namestringYesDisplay name for the agent
descriptionstringYesDescription of what the agent does
instructionsstringYesSystem prompt that guides the agent’s behavior
outputSchemastringNoJSON schema for structured agent output
serversobject[]NoMCP servers and tools to grant access to. Each entry has a name (server name) and tools (map of tool names to config objects — use {} for defaults). Defaults to [].
workflowsobject[]NoWorkflows the agent can trigger. Each entry has triggerName, workflowName, triggerUrl, and triggerApiKey.
bindToWorkflowobjectNoBind the agent to a workflow after creation. Has automationId and resourceName.
The datastores, filestores, and knowledgeBases parameters exist but are not yet supported. Do not use them.
Response fields:
FieldTypeDescription
idstringAgent ID
namestringAgent name
descriptionstringAgent description
instructionsstringAgent system prompt
createdDatestringCreation timestamp
Example: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_agent_create",
      "arguments": {
        "name": "Research Assistant",
        "description": "An agent that researches topics and summarizes findings",
        "instructions": "You are a research assistant. When given a topic, search the web and provide a concise summary with sources."
      }
    },
    "id": 1
  }'
Response: 
{
  "structuredContent": {
    "id": "ua_abc123",
    "name": "Research Assistant",
    "description": "An agent that researches topics and summarizes findings",
    "instructions": "You are a research assistant...",
    "createdDate": "2026-02-15T10:00:00Z"
  }
}

​
agent_list

List all agents accessible to the current user. Parameters: None Response fields:
FieldTypeDescription
agentsobject[]Array of agent summaries
agents[].idstringAgent ID
agents[].namestringAgent name
agents[].descriptionstringAgent description
Example: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_agent_list",
      "arguments": {}
    },
    "id": 1
  }'
Response: 
{
  "structuredContent": {
    "agents": [
      { "id": "ua_abc123", "name": "Research Assistant", "description": "..." },
      { "id": "ua_def456", "name": "Code Reviewer", "description": "..." }
    ]
  }
}

​
agent_read

Get the full configuration of a specific agent, including its instructions, server access, and metadata. Parameters:
ParameterTypeRequiredDescription
agentIdstringYesID of the agent to retrieve (e.g. ua_abc123)
Response fields:
FieldTypeDescription
idstringAgent ID
namestringAgent name
descriptionstringAgent description
instructionsstringAgent system prompt
serversobject[]MCP servers configuration
workflowsobject[]Workflows configuration
createdDatestringCreation timestamp
lastModifiedstringLast modification timestamp
versionnumberVersion number
Example: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_agent_read",
      "arguments": { "agentId": "ua_abc123" }
    },
    "id": 1
  }'
Response: 
{
  "structuredContent": {
    "id": "ua_abc123",
    "name": "Research Assistant",
    "description": "An agent that researches topics and summarizes findings",
    "instructions": "You are a research assistant...",
    "servers": [],
    "workflows": [],
    "createdDate": "2026-02-15T10:00:00Z",
    "lastModified": "2026-02-15T10:00:00Z",
    "version": 1
  }
}

​
agent_update

Update an existing agent. Only the fields you provide are changed — omitted fields remain unchanged. Parameters:
ParameterTypeRequiredDescription
agentIdstringYesID of the agent to update
namestringNoUpdated display name
descriptionstringNoUpdated description
instructionsstringNoUpdated system prompt
outputSchemastringNoUpdated JSON schema for structured output
serversobject[]NoUpdated MCP server access. Replaces existing servers entirely.
workflowsobject[]NoUpdated workflows configuration
Example: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_agent_update",
      "arguments": {
        "agentId": "ua_abc123",
        "instructions": "You are an updated research assistant with new capabilities."
      }
    },
    "id": 1
  }'
Response: Returns the full updated agent object (same shape as agent_read).

​
agent_invoke

Send a message to an agent and get a response. This is the primary way to interact with agents.
  • Without chatId: Starts a new conversation. The response includes a chatId you can use to continue.
  • With chatId: Continues an existing conversation with full message history.
Parameters:
ParameterTypeRequiredDescription
agentIdstringYesID of the agent to invoke
messagestringYesThe message to send to the agent
chatIdstringNoChat ID to continue an existing conversation. If omitted, a new conversation is started.
modestringNoAgent mode: "action_agent" (GPT-based, default) or "claude_agent" (Claude-based)
messagesInResponsebooleanNoIf true, includes the full message history in the response
Response fields:
FieldTypeDescription
successbooleanWhether the invocation was successful
responsestringThe agent’s response message
chatIdstringChat ID for continuing the conversation
agentIdstringID of the invoked agent
messagesobject[]Full message history (only if messagesInResponse was true)
Example — start a new conversation: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_agent_invoke",
      "arguments": {
        "agentId": "ua_abc123",
        "message": "Research the latest developments in quantum computing"
      }
    },
    "id": 1
  }'
Response: 
{
  "structuredContent": {
    "success": true,
    "response": "Here are the latest developments in quantum computing...",
    "chatId": "auto_xyz789",
    "agentId": "ua_abc123"
  }
}
Example — continue the conversation: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_agent_invoke",
      "arguments": {
        "agentId": "ua_abc123",
        "chatId": "auto_xyz789",
        "message": "Can you focus on error correction specifically?"
      }
    },
    "id": 1
  }'

​
chat_create

Create a new chat session for an agent without sending a message. Useful when you need a chatId before invoking the agent — for example, to use with code execution artifacts.
You don’t always need chat_create. Calling agent_invoke without a chatId automatically creates a new chat and returns its ID.
Parameters:
ParameterTypeRequiredDescription
agentIdstringYesID of the agent to create a chat for
namestringNoDisplay name for the chat. Defaults to "Chat with agent <agentId>".
Response fields:
FieldTypeDescription
idstringChat ID (use as chatId in agent_invoke)
agentIdstringAgent ID this chat is associated with
namestringChat display name
createdDatestringCreation timestamp
Example: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_chat_create",
      "arguments": {
        "agentId": "ua_abc123",
        "name": "Quantum Computing Research"
      }
    },
    "id": 1
  }'
Response: 
{
  "structuredContent": {
    "id": "auto_xyz789",
    "agentId": "ua_abc123",
    "name": "Quantum Computing Research",
    "createdDate": "2026-02-15T10:30:00Z"
  }
}

​
chat_list

List all chat sessions, optionally filtered to a specific agent. Parameters:
ParameterTypeRequiredDescription
agentIdstringNoFilter to chats for this agent only. If omitted, returns all chats.
Response fields:
FieldTypeDescription
chatsobject[]Array of chat summaries
chats[].idstringChat ID
chats[].agentIdstringAssociated agent ID
chats[].namestringChat display name
chats[].createdDatestringCreation timestamp
chats[].lastModifiedstringLast modification timestamp
Example: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_chat_list",
      "arguments": { "agentId": "ua_abc123" }
    },
    "id": 1
  }'
Response: 
{
  "structuredContent": {
    "chats": [
      {
        "id": "auto_xyz789",
        "agentId": "ua_abc123",
        "name": "Quantum Computing Research",
        "createdDate": "2026-02-15T10:30:00Z",
        "lastModified": "2026-02-15T11:00:00Z"
      }
    ]
  }
}

​
chat_reset_conversation

Clear all messages in a chat. The chat itself is preserved and can be reused — only the conversation history is wiped. Parameters:
ParameterTypeRequiredDescription
chatIdstringYesID of the chat to reset
Response fields:
FieldTypeDescription
successbooleanWhether the conversation was successfully reset
chatIdstringID of the chat that was reset
Example: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_chat_reset_conversation",
      "arguments": { "chatId": "auto_xyz789" }
    },
    "id": 1
  }'
Response: 
{
  "structuredContent": {
    "success": true,
    "chatId": "auto_xyz789"
  }
}

​
chat_list_artifacts

List all artifacts (files) associated with a chat. Artifacts are created by agents during code execution via createArtifact(), or uploaded by users. Parameters:
ParameterTypeRequiredDescription
chatIdstringYesID of the chat to list artifacts for
Response fields:
FieldTypeDescription
artifactsobject[]Array of artifact metadata
artifacts[].idstringArtifact ID
artifacts[].sourceFileNamestringOriginal file name
artifacts[].mimeTypestringMIME type (e.g. application/pdf)
artifacts[].sourceSizeBytesnumberFile size in bytes
artifacts[].urlstringSigned download URL
artifacts[].fileTypestringArtifact type classification
artifacts[].versionnumberVersion number
artifacts[].versionDatestringLast update timestamp
Example: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_chat_list_artifacts",
      "arguments": { "chatId": "auto_xyz789" }
    },
    "id": 1
  }'
Response: 
{
  "structuredContent": {
    "artifacts": [
      {
        "id": "file_abc",
        "sourceFileName": "report.pdf",
        "mimeType": "application/pdf",
        "sourceSizeBytes": 45230,
        "url": "https://...",
        "fileType": "document",
        "version": 1,
        "versionDate": "2026-02-15T11:00:00Z"
      }
    ]
  }
}