Pinkfish Agents

Create, manage, and interact with Pinkfish agents and their conversations programmatically

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). To give an agent tool access, pass the servers parameter with MCP server names and tool names — use capabilities_discover to find valid values.
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

Tool	Description
agent_create	Create a new agent with instructions and tool access
agent_list	List all accessible agents
agent_read	Get full agent configuration and metadata
agent_update	Update agent fields (partial update)
agent_invoke	Send a message to an agent and get a response
chat_create	Create a chat session for an agent
chat_list	List chat sessions, optionally filtered by agent
chat_reset_conversation	Clear conversation history in a chat
chat_list_artifacts	List artifacts (files) in a chat
agent_publish_release	Publish a versioned release snapshot of an agent (required before it can be a public template)
agent_toggle_public_template	Add or remove the agent from the public template gallery

See the full server reference for parameters, schemas, and response formats for each tool.