---
title: "Create agent"
method: POST
path: "/agents/create"
tags: ["Agents"]
---

# Create agent

`POST /agents/create`

Create a new custom AI agent.

**Overview:**
Agents are specialized AI assistants configured for specific tasks.
They can have custom system prompts, access to specific tools, and
be limited to certain knowledge bases.

**Agent Configuration:**
- **System prompt:** Instructions that define agent behavior
- **Tools:** Capabilities like web search, code execution, etc.
- **Knowledge bases:** Data sources the agent can access
- **Model config:** AI model settings (temperature, max tokens)

**Use Cases:**
- Customer support bot with product knowledge
- Code review assistant with repository access
- HR assistant with policy documents

## Request body

- AgentCreateRequest
  - `name` string, required — Agent display name
  - `description` string — What the agent does
  - `startMessage` string — Initial greeting shown when conversation starts
  - `systemPrompt` string — System instructions for the agent
  - `instructions` string — Additional agent execution instructions
  - `models` AgentCreateModelEntry[], required — Agent model configuration entries. The gateway requires at least one object entry with `isReasoning: true`. String-only arrays are schema-valid but rejected at runtime with HTTP 400.
    - union — Accepted model entry for `POST /agents/create`. The gateway accepts either a non-empty string model entry or an object entry with a required `modelKey`. The `models` array must include at least one object entry with `isReasoning: true`. String-only entries are schema-valid but are rejected at the gateway with HTTP 400.
      - string
      - object
        - `modelKey` string, required
        - `modelName` string
        - `provider` string
        - `isReasoning` boolean
  - `tags` string[]
  - `shareWithOrg` boolean — Share agent with the organization
  - `isServiceAccount` boolean — Create the agent as a service-account agent
  - `toolsets` AgentCreateToolset[] — Toolsets attached to the agent (instance-aware)
    - `name` 'calendar' | 'clickup' | 'confluence' | 'drive' | 'github' | 'gmail' | 'jira' | 'lumos' | 'mariadb' | 'onedrive' | 'outlook' | 'redshift' | 'salesforce' | 'sharepoint' | 'slack' | 'teams' | 'zoom', required — Registered toolset name (lowercase) accepted by the create-agent gateway.
    - `displayName` string
    - `type` string
    - `instanceId` string
    - `instanceName` string
    - `tools` AgentCreateToolRef[]
      - `name` string, required
      - `fullName` string
      - `description` string
  - `knowledge` AgentCreateKnowledge[] — Knowledge sources connected to the agent
    - `connectorId` string, required
    - `filters` union
      - AgentKnowledgeFiltersParsed — Indexed scope for a knowledge connector: record-group ids (collections / KB roots) and individual record ids. First-party create/update flows set `recordGroups` and `records`. On GET, `filtersParsed` is this shape parsed from the stored `filters` JSON string.
        - `recordGroups` string[] — Record-group ids (e.g. knowledge-base roots) in scope.
        - `records` string[] — Individual record ids in scope.
      - string
      - unknown[]
        - unknown
  - `webSearch` union — Accepted web-search attachment for `POST /agents/create`. The gateway accepts either a provider string or an object with at least a `provider` field.
    - string
    - object
      - `provider` string, required
      - `providerKey` string
      - `providerLabel` string
      - `iconPath` string

## Response `201`

Agent created

- AgentCreateResponse
  - `status` 'success' | 'partial_success', required
  - `message` string, required
  - `agent` AgentCreateResponseAgent, required
    - `_key` string, required
    - `name` string, required
    - `description` string, required
    - `startMessage` string, required
    - `systemPrompt` string, required
    - `instructions` string, nullable, required
    - `models` string[], required
    - `tags` string[], required
    - `webSearch` object, required
      - `provider` string
      - `providerKey` string
      - `providerLabel` string
    - `isActive` boolean, required
    - `isServiceAccount` boolean, required
    - `createdBy` string, required
    - `updatedBy` string, nullable, required
    - `createdAtTimestamp` integer, required
    - `updatedAtTimestamp` integer, required
    - `isDeleted` boolean, required
    - `toolsets` AgentCreateResponseToolset[], required
      - `name` 'calendar' | 'clickup' | 'confluence' | 'drive' | 'github' | 'gmail' | 'jira' | 'lumos' | 'mariadb' | 'onedrive' | 'outlook' | 'redshift' | 'salesforce' | 'sharepoint' | 'slack' | 'teams' | 'zoom', required — Registered toolset name (lowercase) accepted by the create-agent gateway.
      - `displayName` string, required — Human-readable toolset product label (for example `Jira` or `Slack`).
      - `key` string, required
      - `tools` AgentCreateResponseTool[], required
        - `name` string, required
        - `fullName` string, required
        - `key` string, required
    - `knowledge` AgentCreateResponseKnowledge[], required
      - `connectorId` string, required
      - `key` string, required
      - `filters` union, required
        - object
        - string
        - unknown[]
          - unknown
  - `warnings` AgentCreateWarning[]
    - `name` string
    - `error` string

## Other responses

- `400` — Invalid agent configuration
- `401` — Unauthorized

---

[API](https://skmtc.net/pipeshub-ai/apis/pipeshub-api.md) · [All operations](https://skmtc.net/pipeshub-ai/apis/pipeshub-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pipeshub-ai/pipeshub-api/versions/abd27cfefc73/schema)