Skip to main content
Create agents, start conversations, and retrieve artifacts — all via JSON-RPC 2.0 through the agent-management MCP server.

​
Overview

The agent management tools let you build applications that:
  • Create and configure agents with custom instructions and tool access
  • Have conversations with agents across multiple messages
  • Manage chat sessions — list, create, and reset conversations
  • Retrieve artifacts — list files created by agents during code execution
A typical flow:
  1. Create an agent with agent_create (or use an existing one via agent_list)
  2. Invoke the agent with agent_invoke — this starts a conversation and returns a chatId
  3. Continue the conversation by calling agent_invoke again with the same chatId
  4. List artifacts created during the conversation with chat_list_artifacts
For full tool parameters and schemas, see the agent-management server reference.

​
Authentication

All calls require a runtime token. See Authentication for how to exchange your API key. 
export PINKFISH_TOKEN=$(curl -s -X POST "https://app-api.app.pinkfish.ai/auth/token" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Selected-Org: YOUR_ORG_ID" \
  -H "Content-Type: application/json" | jq -r '.token')

​
Quick Start

​
Create an agent

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
  }'

​
Start a 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"
  }
}

​
Continue the conversation

Pass the chatId from the previous response to continue with message history: 
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
  }'

​
Available 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
See the full server reference for parameters, schemas, and response formats for each tool.