---
title: "Create an agent [write]"
method: POST
path: "/agents"
---

# Create an agent \[write\]

`POST /agents`

## Request

- Base URL: `https://api.agentsky.dev/v1`
- URL: `https://api.agentsky.dev/v1/agents`
- Auth: HTTP bearer

An agent is a reusable configuration — engine, prompt, capabilities, secrets. Every field is optional: an empty body creates the default pi agent with no built-in capabilities (capabilities are explicit opt-in; unknown ids → 400). The response's `id` (agent_…) is the agent's only address. One agent can run many sessions; creating the agent provisions nothing — session creation provisions the pod by default (POST /v1/sessions supports deferred provisioning). Optional Idempotency-Key safely replays the original 201 response within the same user and universe; changing the body with the same key returns 409 idempotency_conflict. Keys do not expire.

## Headers

- `Idempotency-Key` string

## Request body

- CreateAgent
  - `name` string: Prompt label only — not an address. An agent is addressed by the `id` in the response (agent_…); names are free and need not be unique
  - `description` string
  - `agentType` 'hermes' | 'claude_code' | 'codex' | 'openclaw' | 'pi' | 'dsh' | 'kimi_code' | 'opencode' | 'jev' | 'agoragentic_acp' | 'amp_acp' | 'auggie' | 'autohand' | 'cline' | 'codebuddy_code' | 'cortex_code' | 'corust_agent' | 'crow_cli' | 'cursor' | 'deepagents' | 'devin' | 'dimcode' | 'dirac' | 'factory_droid' | 'fast_agent' | 'gemini' | 'github_copilot_cli' | 'glm_acp_agent' | 'antigravity_acp' | 'goose' | 'grok_build' | 'harn' | 'junie' | 'kilo' | 'kimchi' | 'minimax_code' | 'minion_code' | 'mistral_vibe' | 'nova' | 'poolside' | 'qoder' | 'qwen_code' | 'sigit' | 'stakpak' | 'vtcode' | 'code_assistant' | 'docker_cagent' | 'kiro' | 'openhands' | 'muse_code' | 'workspace_acp'
  - `llm` string
  - `reasoningEffort` 'none' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra': Harness/model-compatible reasoning effort; omitted = model-compatible fallback for constrained models, otherwise harness default. Explicit values must fit both agentType and llm — agoragentic_acp: not supported; amp_acp: not supported; auggie: not supported; autohand: not supported; cline: not supported; codebuddy_code: not supported; cortex_code: not supported; corust_agent: not supported; crow_cli: not supported; cursor: not supported; deepagents: not supported; devin: not supported; dimcode: not supported; dirac: not supported; factory_droid: not supported; fast_agent: not supported; gemini: not supported; github_copilot_cli: not supported; glm_acp_agent: not supported; antigravity_acp: not supported; goose: not supported; grok_build: not supported; harn: not supported; junie: not supported; kilo: not supported; kimchi: not supported; minimax_code: not supported; minion_code: not supported; mistral_vibe: not supported; nova: not supported; poolside: not supported; qoder: not supported; qwen_code: not supported; sigit: not supported; stakpak: not supported; vtcode: not supported; code_assistant: not supported; docker_cagent: not supported; kiro: not supported; muse_code: not supported; openhands: not supported; hermes: none/minimal/low/medium/high/xhigh/max/ultra; claude_code: low/medium/high/xhigh/max; codex: none/minimal/low/medium/high/xhigh/max; openclaw: not supported; jev: not supported; pi: off/minimal/low/medium/high/xhigh/max; dsh: not supported; kimi_code: not supported; opencode: none/minimal/low/medium/high/xhigh/max; workspace_acp: not supported; models: claude-fable-5-1: low/medium/high/xhigh/max; claude-fable-5: low/medium/high/xhigh/max; claude-opus-5-5: low/medium/high/xhigh/max; claude-opus-5: low/medium/high/xhigh/max; claude-opus-4-8: low/medium/high/xhigh/max; claude-sonnet-5-5: low/medium/high/xhigh/max; claude-sonnet-5: low/medium/high/xhigh/max; claude-sonnet-4-6: low/medium/high/max; claude-haiku-5-5: low/medium/high/xhigh/max; claude-haiku-4-5: not supported; gpt-6.1-sol: low/medium/high/xhigh/max; gpt-6-astra: low/medium/high/xhigh/max; gpt-6-sol: none/low/medium/high/xhigh/max; gpt-6-luna: none/low/medium/high/xhigh/max; gpt-5.6-sol: none/low/medium/high/xhigh/max; gpt-5.6-terra: none/low/medium/high/xhigh/max; gpt-5.6-luna: none/low/medium/high/xhigh/max; gpt-5.5: none/low/medium/high/xhigh; gpt-4.1: not supported; deepseek-v4-pro: low/high/max; deepseek-flash: low/high/max; kimi-k3.1-pro: low/high/max; kimi-k3: low/high/max; kimi-k2.7-code: not supported; minimax-m3: not supported; muse-spark-1.1: minimal/low/medium/high/xhigh; muse-spark-1.2: minimal/low/medium/high/xhigh; muse-spark-1.3: minimal/low/medium/high/xhigh/max; minimax-m3.1-flash: low/medium/high/xhigh/max; gemini-4-argon: low/medium/high; gemini-3.5-flash-lite: low/medium/high; gemini-3.8-flash: low/medium/high; gemini-3.5-flash: low/medium/high; glm-5.3: low/high/max; glm-5.3-flash: low/high/max; grok-4.6: low/medium/high; grok-4.7: low/medium/high/xhigh
  - `prompt` string
  - `displayName` string: What the agent is called in the console and in channels; omitted = an auto-generated asteroid name
  - `capabilities` string[]
  - `instructions` object[]
    - `name` string, required
    - `content` string
  - `skills` union[]: RFC-0073 skill attachments: store references ({type:'skill', skillId, version?: 'latest'|skr_…}) and GitHub shortcuts ({type:'github', url, ref?, tokenSecretRef?}). Max 20.
    - union
      - object
        - `type` 'skill', required
        - `skillId` string, required
        - `version` string
      - object
        - `type` 'github', required
        - `url` string, uri, required
        - `ref` string: Branch or commit SHA; default branch when omitted.
        - `tokenSecretRef` string: Agent secret key holding a clone token for private repos.
  - `mcpServers` object[]: Remote streamable-HTTP MCP servers this agent connects to.
    - `type` 'url'
    - `name` string, required
    - `url` string, uri, required
    - `tools` object
      - `include` string[]
      - `exclude` string[]
  - `hooks` object[]: Shell commands run in the session's pod at lifecycle events ({event, command, matcher?, timeout_s?}). Every harness accepts every event; a hook can stop a prompt or a tool call only on a harness whose own hook system fires that event. Max 20.
    - `event` 'pre_session_start' | 'session_start' | 'user_prompt_submit' | 'pre_tool_use' | 'post_tool_use' | 'stop' | 'session_end', required
    - `command` string, required
    - `matcher` string
    - `timeout_s` integer
  - `customData` object[]
    - `id` string, required
    - `name` string, required
    - `kind` 'spreadsheet' | 'doc' | 'private_api' | 'other', required
    - `scope` 'creator' | 'user'
    - `description` string
    - `uri` string
    - `config` object
  - `metadata` object
  - `environmentId` string: The workspace environment this agent is built for: a session boots in it when its create names no `environment_id` (ahead of the workspace default), and a create naming an environment that neither is it nor extends it is 409 `environment_mismatch`. Omitted = no link.
  - `browserProfile` union: The browser this agent's sessions open with when they name none: mine, fresh or user:<user id>. Applies to sessions created afterwards
    - 'mine' | 'fresh' | 'workspace' | 'private'
    - string
  - `vaultId` string: A workspace vault every session of this agent carries: after the vaults the session create names, ahead of the workspace default. Omitted = no agent vault.
  - `capabilityPolicies` object
  - `nativeToolPolicy` 'always_allow' | 'always_ask': Owner-only permission for native pod tools; omitted defaults to always_allow. Supported by Claude Code and Codex after native approval rollout.
  - `hiringPolicy` 'allow' | 'deny': Whether this agent's sessions may bring in other agents as helpers; omitted defaults to allow. deny makes the agent work alone.
  - `harness` string: workspace_acp only: the public id (hrn_…) of the workspace harness to pin. Required when agentType is workspace_acp.
  - `handle` string: Workspace-scoped @handle. Lower-case, 2–40 chars: [a-z0-9_]. Unique within a workspace. Reserves the address handle@agents.agentsky.dev, returned as `email`; that domain does not receive mail yet.
  - `channel_settings` object: Channel persona settings for Slack/Lark.
    - `invitable` boolean, required
    - `description` string
  - `runtime` union: BYO-code runtime config. {kind:'endpoint',protocol:'a2a'|'acp'|'mcp',url} or {kind:'image',image}.
    - object
      - `kind` 'endpoint', required
      - `protocol` 'a2a' | 'acp' | 'mcp', required
      - `url` string, uri, required
    - object
      - `kind` 'image', required
      - `image` string, required

## Response `201`

Created

- object
  - `agent` AgentDetail, required: Everything in the list item, plus configuration state.
    - `id` string: The agent id (agent_…) — the only address
    - `name` string
    - `displayName` string
    - `agentType` string
    - `llm` string
    - `harnessVersion` string, nullable
    - `reasoningEffort` 'none' | 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'ultra' | 'null', nullable
    - `version` integer
    - `archived` boolean
    - `sessionCount` integer
    - `createdAt` string
    - `description` string, nullable
    - `prompt` string, nullable: The user prompt layer
    - `promptVersion` integer, nullable
    - `capabilities` string[]: The built-in capabilities this agent is granted — the exact set its sessions may execute (enforced; empty = none). Ids are listed at /docs/capabilities.
    - `capabilityPolicies` object: Per-capability permission policy map; omitted when no entries exist. always_allow: invoke without user confirmation. always_ask: prompt the session owner before every invocation. auto: reserved for future policy evaluation; currently prompts the session owner like always_ask.
    - `nativeToolPolicy` 'always_allow' | 'always_ask': Native pod-tool permission, independent of capabilities. Returned on create and detail responses; omitted legacy settings mean always_allow. Only the agent owner can change it, while sessions are idle.
    - `hiringPolicy` 'allow' | 'deny': Whether this agent's sessions may bring in other agents as helpers. allow unless set to deny. Returned on create and detail responses.
    - `mcpServers` object[]: Declared remote MCP server references, including tool filters; runtime authentication fields are never returned
      - `type` 'url'
      - `name` string, required
      - `url` string, uri, required
      - `tools` object
        - `include` string[]
        - `exclude` string[]
    - `hooks` object[]: Shell commands run in the session's pod at lifecycle events
      - `event` 'pre_session_start' | 'session_start' | 'user_prompt_submit' | 'pre_tool_use' | 'post_tool_use' | 'stop' | 'session_end', required
      - `command` string, required
      - `matcher` string
      - `timeout_s` integer
    - `metadata` object: Your key-merged client metadata
    - `environmentId` string, nullable: The environment sessions of this agent boot in when their create names none; ahead of the workspace default
    - `vaultId` string, nullable: The vault every session of this agent carries, after the vaults its create names and ahead of the workspace default
    - `defaultSessionId` string, nullable: The session conversation verbs target when addressed by agent id
    - `universe` string: Resolved universe slug

## Other responses

- `default`: Error — { error: { code, message, request_id } }

## Changes

- **2026-11-02** `e5e8f0229a99`: 1 breaking, 11 warning, 39 info
  - removed the enum value `agentpool` of the request property `agentType`
  - added the new `code-review` enum value to the `agent/capabilities/items/` response property for the response status `201`
  - added the new `dictionary.define` enum value to the `agent/capabilities/items/` response property for the response status `201`
  - added the new `elevenlabs.music` enum value to the `agent/capabilities/items/` response property for the response status `201`
  - …47 more

[Operation history](https://skmtc.dev/agentsky/apis/agentsky-developer-api/changes/agents/post.md)

---

[API](https://skmtc.dev/agentsky/apis/agentsky-developer-api.md) - [All operations](https://skmtc.dev/agentsky/apis/agentsky-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/agentsky/apis/agentsky-developer-api/revisions/0d435187cd55?raw)