---
title: "Create new agent (Enterprise)"
method: POST
path: "/api/v1/agents"
tags: ["Agents"]
---

# Create new agent (Enterprise)

`POST /api/v1/agents`

## Request

- Base URL: `https://orchestrator.getaxonflow.com`
- URL: `https://orchestrator.getaxonflow.com/api/v1/agents`
- Auth: none declared
- TypeScript: <https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/docs/api/v1/agents/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new agent configuration in the database.
**Enterprise only** - requires database-backed storage.

The agent is created with version 1 and marked as active by default.
A version history entry is automatically created.

## Request body

- CreateAgentRequest
  - `name` string, required: Agent name (lowercase, alphanumeric, hyphens, underscores)
  - `domain` string: Agent domain
  - `description` string
  - `is_active` boolean
  - `config` AgentConfigSpec, required: Agent configuration specification
    - `execution` object
      - `default_mode` 'auto' | 'parallel' | 'sequential'
      - `max_parallel_tasks` integer
      - `timeout_seconds` integer
    - `agents` AgentDefinition[]
      - `name` string, required
      - `type` 'llm-call' | 'connector-call', required
      - `llm` object: LLM config (required for llm-call type)
        - `provider` string
        - `model` string
      - `connector` object: Connector config (required for connector-call type)
        - `name` string
        - `operation` string
    - `routing` RoutingRule[]
      - `pattern` string, required: Regex pattern to match
      - `agent` string, required: Target agent name
      - `priority` integer: Higher priority rules match first

## Response `201`

Agent created

- AgentResponse
  - `agent` AgentResource
    - `id` string: Qualified ID (domain/name)
    - `name` string: Agent name
    - `domain` string: Agent domain
    - `description` string: Agent description
    - `version` integer: Version number
    - `is_active` boolean: Whether agent is active
    - `config` AgentConfigSpec: Agent configuration specification
      - `execution` object
        - `default_mode` 'auto' | 'parallel' | 'sequential'
        - `max_parallel_tasks` integer
        - `timeout_seconds` integer
      - `agents` AgentDefinition[]
        - `name` string, required
        - `type` 'llm-call' | 'connector-call', required
        - `llm` object: LLM config (required for llm-call type)
          - `provider` string
          - `model` string
        - `connector` object: Connector config (required for connector-call type)
          - `name` string
          - `operation` string
      - `routing` RoutingRule[]
        - `pattern` string, required: Regex pattern to match
        - `agent` string, required: Target agent name
        - `priority` integer: Higher priority rules match first
    - `created_at` string, date-time
    - `updated_at` string, date-time

## Other responses

- `400`: Invalid request or validation error
- `409`: Agent with same name already exists

---

[API](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-orchestrator-api/revisions/f408ef3ec9dd?raw)