---
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[] — Agent model configuration entries. Optional — an agent created without any models (an empty array or an omitted field) uses the organization's default LLM at chat time. When at least one model entry IS provided, the gateway requires at least one object entry with `isReasoning: true`. String-only arrays are schema-valid but rejected at runtime with HTTP 400 unless the array is empty.
    - 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 itself is optional and may be empty (the agent then uses the organization's default LLM). When the array is non-empty, it must include at least one object entry with `isReasoning: true`. String-only entries are schema-valid but, if present without any reasoning-flagged object entry, 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' | 'confluencedatacenter' | 'drive' | 'github' | 'gmail' | 'jira' | 'jiradatacenter' | '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 and individual record ids. On GET, `filtersParsed` is this shape parsed from the stored `filters` JSON string.
        - `recordGroups` string[] — Deprecated/legacy: record-group ids for connector record-group scoping (e.g. Confluence spaces, Jira projects). No longer set for KB (Collection) entries — a KB is identified by its own `connectorId`, not by an id in this list.
        - `records` string[] — Individual record ids in scope.
      - string
      - unknown[]
        - unknown
  - `skills` AgentSkillAssignment[] — Existing skills to assign to the agent
    - `name` string, required — Lowercase skill name using single hyphens between segments.
  - `webSearch` union — Web-search attachment for an agent. 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
  - `defaultReasoningEffort` 'none' | 'low' | 'medium' | 'high' | 'max', nullable — Agent-level reasoning effort used when a chat request omits its own.

## 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
    - `defaultReasoningEffort` 'none' | 'low' | 'medium' | 'high' | 'max', nullable — Agent-level reasoning effort used when a chat request omits its own. Null when unset.
    - `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' | 'confluencedatacenter' | 'drive' | 'github' | 'gmail' | 'jira' | 'jiradatacenter' | '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
    - `mcpServers` AgentCreateResponseMcpServer[], required
      - `name` string, required
      - `displayName` string, required — Human-readable MCP server product label (for example `Jira MCP`).
      - `key` string, required
      - `tools` AgentCreateResponseMcpServerTool[], 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
    - `skills` AgentCreateResponseSkill[], required
      - `name` string, required
  - `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/revisions/64bfe76b130e/schema)