Custom Agents API

The Custom Agents API allows you to create specialized agents with custom personalities, behaviors, and configurations.

Overview

Custom agents extend DeerFlow with:

SOUL.md: Agent personality and behavioral guardrails
Model override: Use specific LLM for this agent
Tool groups: Restrict available tools
USER.md: Global user profile injected into all custom agents

Base URL: http://localhost:8001/api

List Custom Agents

Get all custom agents available in the agents directory.

GET /agents

Response

agents

array

Array of agent objects

Show Agent object

name

string

Agent identifier (hyphen-case)

description

string

Agent description

model

string

Optional model override

tool_groups

array

Optional tool group whitelist

Example

curl http://localhost:8001/api/agents

Response

{
  "agents": [
    {
      "name": "code-reviewer",
      "description": "Expert code reviewer with focus on best practices",
      "model": "gpt-4",
      "tool_groups": ["sandbox"]
    },
    {
      "name": "researcher",
      "description": "Research specialist with web access",
      "model": null,
      "tool_groups": ["sandbox", "research"]
    }
  ]
}

Check Agent Name

Validate an agent name and check availability.

GET /agents/check?name={name}

Parameters

name

string

required

Agent name to check (must match ^[A-Za-z0-9-]+$)

Response

available

boolean

Whether the name is available (case-insensitive)

name

string

Normalized name (lowercase)

Example

curl "http://localhost:8001/api/agents/check?name=Code-Reviewer"

Response

{
  "available": false,
  "name": "code-reviewer"
}

Get Custom Agent

Retrieve details and SOUL.md content for a specific agent.

GET /agents/{name}

Parameters

name

string

required

Agent name

Response

name

string

Agent identifier

description

string

Agent description

model

string

Optional model override

tool_groups

array

Optional tool group whitelist

soul

string

SOUL.md content (included in GET only)

Example

curl http://localhost:8001/api/agents/code-reviewer

Response

{
  "name": "code-reviewer",
  "description": "Expert code reviewer",
  "model": "gpt-4",
  "tool_groups": ["sandbox"],
  "soul": "# Code Reviewer\\n\\nYou are an expert code reviewer...\\n"
}

Create Custom Agent

Create a new custom agent with config and SOUL.md.

POST /agents

Request Body

name

string

required

Agent name (must match ^[A-Za-z0-9-]+$, stored as lowercase)

description

string

default:""

Agent description

model

string

Optional model override (e.g., “gpt-4”, “claude-3-opus”)

tool_groups

array

Optional tool group whitelist (e.g., [“sandbox”, “research”])

soul

string

default:""

SOUL.md content - agent personality and behavioral guardrails

Response

Returns the created agent object with all fields including SOUL.md content.

Example

curl -X POST http://localhost:8001/api/agents \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "data-scientist",
    "description": "Expert in data analysis and visualization",
    "model": "gpt-4",
    "tool_groups": ["sandbox", "research"],
    "soul": "# Data Scientist\\n\\nYou are an expert data scientist...\\n"
  }'

Response

{
  "name": "data-scientist",
  "description": "Expert in data analysis and visualization",
  "model": "gpt-4",
  "tool_groups": ["sandbox", "research"],
  "soul": "# Data Scientist\\n\\nYou are an expert data scientist...\\n"
}

Agent names are case-insensitive and normalized to lowercase for storage.

Update Custom Agent

Update an existing agent’s config and/or SOUL.md.

PUT /agents/{name}

Parameters

name

string

required

Agent name

Request Body

All fields are optional. Only provided fields will be updated.

description

string

Updated description

model

string

Updated model override

tool_groups

array

Updated tool group whitelist

soul

string

Updated SOUL.md content

Response

Returns the updated agent object with all fields.

Example

curl -X PUT http://localhost:8001/api/agents/data-scientist \\
  -H "Content-Type: application/json" \\
  -d '{
    "description": "Senior data scientist with ML expertise",
    "soul": "# Data Scientist\\n\\nYou are a senior data scientist...\\n"
  }'

Delete Custom Agent

Delete a custom agent and all its files.

DELETE /agents/{name}

Parameters

name

string

required

Agent name

Response

Returns 204 No Content on success.

Example

curl -X DELETE http://localhost:8001/api/agents/data-scientist

This permanently deletes the agent directory including config.yaml, SOUL.md, and any agent-specific memory.

Get User Profile

Read the global USER.md file injected into all custom agents.

GET /user-profile

Response

content

string

USER.md content, or null if not yet created

Example

curl http://localhost:8001/api/user-profile

Response

{
  "content": "# About Me\\n\\nI'm a software engineer...\\n"
}

Update User Profile

Write the global USER.md file that describes you to all agents.

PUT /user-profile

Request Body

content

string

default:""

USER.md content - your background, preferences, and context

Response

content

string

The saved content

Example

curl -X PUT http://localhost:8001/api/user-profile \\
  -H "Content-Type: application/json" \\
  -d '{
    "content": "# About Me\\n\\nI am a senior software engineer at TechCorp, specializing in distributed systems and microservices architecture. I prefer Python and Go for backend development.\\n\\n## Preferences\\n\\n- Code style: Follow PEP 8 for Python\\n- Testing: Strong believer in TDD\\n- Documentation: Prefer inline comments over external docs\\n"
  }'

SOUL.md Format

SOUL.md defines your custom agent’s personality and behavior:

# Agent Name

Brief description of the agent's role and expertise.

## Personality

- Tone: Professional, concise, technical
- Style: Direct answers with code examples
- Focus: Best practices and maintainability

## Behavioral Guardrails

- Always provide type hints in Python code
- Prefer explicit over implicit
- Test-driven development approach
- Security-first mindset

## Expertise Areas

- Python backend development
- Distributed systems
- Database optimization
- API design

## Communication Style

When reviewing code:
1. Start with positive observations
2. Identify critical issues first
3. Suggest improvements with examples
4. Explain the reasoning behind recommendations

## Tools Preference

Prefer using these tools in this order:
1. read_file - Understand context first
2. bash - Run tests and checks
3. write_file - Apply fixes
4. present_files - Show results

Agent Directory Structure

Custom agents are stored in:

backend/.deer-flow/agents/
├── code-reviewer/
│   ├── config.yaml      # Agent configuration
│   └── SOUL.md          # Agent personality
└── data-scientist/
    ├── config.yaml
    └── SOUL.md

config.yaml:

name: code-reviewer
description: Expert code reviewer with focus on best practices
model: gpt-4
tool_groups:
  - sandbox

Best Practices

Write clear SOUL.md

Define personality, behavioral guardrails, and communication style explicitly.

# Code Reviewer

You are an expert code reviewer focusing on:
- Security vulnerabilities
- Performance optimization
- Code maintainability
- Best practices

Always explain WHY a change is needed.

Use model overrides strategically

Different tasks benefit from different models:

Code review: GPT-4 (strong reasoning)
Content writing: Claude (natural language)
Data analysis: GPT-4 with code interpreter

Restrict tool groups

Limit tools to what the agent needs:

{
  "name": "security-auditor",
  "tool_groups": ["sandbox"],
  "soul": "Only read files, never modify code..."
}

Set up USER.md once

Create a comprehensive USER.md that all agents can reference:

# About Me

Software engineer at TechCorp
- Team: Platform Engineering
- Stack: Python, Go, Kubernetes
- Preferences: TDD, clean code, documentation

Error Codes

404

error

Agent not found

409

error

Agent already exists (when creating)

422

error

Invalid agent name (must match ^[A-Za-z0-9-]+$)

500

error

Internal server error

Next Steps

Gateway API Overview

Learn about other Gateway endpoints

Skills API

Manage skills for your agents

Models Configuration

Configure LLM models

Agent System

Understanding the agent architecture

Python Client

Gateway API

LangGraph API

Agent Tools

​Overview

​List Custom Agents

​Response

​Example

​Check Agent Name

​Parameters

​Response

​Example

​Get Custom Agent

​Parameters

​Response

​Example

​Create Custom Agent

​Request Body

​Response

​Example

​Update Custom Agent

​Parameters

​Request Body

​Response

​Example

​Delete Custom Agent

​Parameters

​Response

​Example

​Get User Profile

​Response

​Example

​Update User Profile

​Request Body

​Response

​Example

​SOUL.md Format

​Agent Directory Structure

​Best Practices

​Error Codes

​Next Steps

Gateway API Overview

Skills API

Models Configuration

Agent System

Build docs developers (and LLMs) love

Overview

List Custom Agents

Response

Example

Check Agent Name

Parameters

Response

Example

Get Custom Agent

Parameters

Response

Example

Create Custom Agent

Request Body

Response

Example

Update Custom Agent

Parameters

Request Body

Response

Example

Delete Custom Agent

Parameters

Response

Example

Get User Profile

Response

Example

Update User Profile

Request Body

Response

Example

SOUL.md Format

Agent Directory Structure

Best Practices

Error Codes

Next Steps