> ## 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.

# 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](/api-reference/mcp-servers/embedded/agent-management).

## Authentication

All calls require a runtime token. See [Authentication](/api-reference/platform/authentication) for how to exchange your API key.

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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:**

```json theme={null}
{
  "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:

```bash theme={null}
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](/api-reference/mcp-servers/embedded/agent-management) for parameters, schemas, and response formats for each tool.