AGagentsky

Create an agent [write]

Changed on

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.

post/agents

Request

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

Headers

Idempotency-Keystring

A unique key for this creation attempt. Preserve the key and body when retrying.

Request body

namestring

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

descriptionstring
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'
llmstring
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

promptstring
displayNamestring

What the agent is called in the console and in channels; omitted = an auto-generated asteroid name

capabilitiesstring[]
metadataobject
environmentIdstring

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.

vaultIdstring

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.

capabilityPoliciesobject
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.

harnessstring

workspace_acp only: the public id (hrn_…) of the workspace harness to pin. Required when agentType is workspace_acp.

handlestring

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.

Response

Created

Changes

  • e5e8f0229a99Revision changes
    • breaking

      removed the enum value agentpool of the request property

    • warning

      added the new code-review enum value to the // response property for the response status

    • warning

      added the new dictionary.define enum value to the // response property for the response status

    • warning

      added the new elevenlabs.music enum value to the // response property for the response status

    • warning

      added the new elevenlabs.tts enum value to the // response property for the response status

    • warning

      added the new frankfurter.fx enum value to the // response property for the response status

    • warning

      added the new googledns.resolve enum value to the // response property for the response status

    • warning

      added the new logo.lookup enum value to the // response property for the response status

    • warning

      added the new openlibrary.search enum value to the // response property for the response status

    • warning

      added the new openmeteo.weather enum value to the // response property for the response status

    • warning

      added the new qrserver.create enum value to the // response property for the response status

    • warning

      added the new recall.meeting-record enum value to the // response property for the response status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new code-review enum value to the request property /

    • info

      added the new code-review enum value to the request property /

    • info

      added the new dictionary.define enum value to the request property /

    • info

      added the new dictionary.define enum value to the request property /

    • info

      added the new elevenlabs.music enum value to the request property /

    • info

      added the new elevenlabs.music enum value to the request property /

    • info

      added the new elevenlabs.tts enum value to the request property /

    • info

      added the new elevenlabs.tts enum value to the request property /

    • info

      added the new frankfurter.fx enum value to the request property /

    • info

      added the new frankfurter.fx enum value to the request property /

    • info

      added the new googledns.resolve enum value to the request property /

    • info

      added the new googledns.resolve enum value to the request property /

    • info

      added the new logo.lookup enum value to the request property /

    • info

      added the new logo.lookup enum value to the request property /

    • info

      added the new muse_code enum value to the request property

    • info

      added the new openlibrary.search enum value to the request property /

    • info

      added the new openlibrary.search enum value to the request property /

    • info

      added the new openmeteo.weather enum value to the request property /

    • info

      added the new openmeteo.weather enum value to the request property /

    • info

      added the new qrserver.create enum value to the request property /

    • info

      added the new qrserver.create enum value to the request property /

    • info

      added the new recall.meeting-record enum value to the request property /

    • info

      added the new recall.meeting-record enum value to the request property /

    • info

      added the new workspace_acp enum value to the request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      the response property became required for the status

    • info

      the response property / became required for the status

    • info

      the response property / became required for the status