---
title: "Create an agent"
method: POST
path: "/agent/identities"
tags: ["agent"]
---

# Create an agent

`POST /agent/identities`

Create a new agent for the caller's team.
Agents can be used as the execution principal for team-owned runs.

## Request body

- CreateAgentRequest
  - `name` string, required — A name for the agent
  - `description` string, nullable — Optional description of the agent
  - `prompt` string, nullable — Optional base prompt for this agent
  - `environment_id` string, nullable — Optional default cloud environment ID for runs executed by this agent. The environment must be owned by the same team as the agent.
  - `secrets` SecretRef[] — Optional list of secrets associated with the agent. Duplicate names within a single request are rejected. Each entry is unioned into the run-time secret scope when the agent executes.
    - `name` string, required — Name of the managed secret.
  - `skills` string[] — Optional list of skill specs to associate with the agent. Format: "{owner}/{repo}:{skill_path}" (e.g., "warpdotdev/warp-server:.claude/skills/deploy/SKILL.md"). Each spec is validated and normalized at attach time using the team's GitHub credentials; inaccessible or malformed specs are rejected.
  - `base_model` string, nullable — Optional base model for runs executed by this agent.
  - `inference_providers` InferenceProvidersConfig — Inference provider settings used for LLM calls.
    - `aws` AwsInferenceProviderConfig — Configures AWS Bedrock as the LLM inference provider for this agent or run.
      - `disabled` boolean — If true, opt out of Bedrock at this layer.
      - `role_arn` string — IAM role ARN to assume when calling Bedrock.
      - `region` string — AWS region used for STS when assuming the Bedrock inference role.
  - `memory_stores` MemoryStoreRef[] — Optional list of memory stores to attach to the agent. Each store must be team-owned by the same team as the agent. Duplicate UIDs within a single request are rejected.
    - `uid` string, required — UID of the memory store.
    - `access` 'read_write' | 'read_only', required — Access level for the store.
    - `instructions` string, required — Instructions for how the agent should use this memory store. Must not be empty.
  - `base_harness` string, nullable — Optional default harness for runs executed by this agent.
  - `harness_auth_secrets` HarnessAuthSecrets — Authentication secrets for third-party harnesses. Only the secret for the harness specified gets injected into the environment.
    - `claude_auth_secret_name` string — Name of a managed secret for Claude Code harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "claude".
    - `codex_auth_secret_name` string — Name of a managed secret for Codex harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "codex".

## Response `201`

Agent created successfully

- AgentResponse
  - `uid` string, required — Unique identifier for the agent
  - `name` string, required — Name of the agent
  - `description` string, nullable — Optional description of the agent
  - `prompt` string, nullable — Optional base prompt for this agent
  - `environment_id` string — Default cloud environment ID for runs executed by this agent. The precedence order for environment resolution is: 1. The environment specified on the run itself 2. The agent's default environment 3. An empty environment
  - `available` boolean, required — Whether this agent is within the team's plan limit and can be used for runs
  - `created_at` string, date-time, required — When the agent was created (RFC3339)
  - `updated_at` string, date-time, required — When the agent was last updated (RFC3339)
  - `secrets` SecretRef[], required — Secrets that this agent may access by default.
    - `name` string, required — Name of the managed secret.
  - `skills` string[], required — Ordered list of normalized skill specs associated with this agent. Always present; empty when no skills are attached.
  - `base_model` string — Base model for runs executed by this agent. The precedence order for model resolution is: 1. The model specified on the run itself 2. The agent's base model 3. The team's default model
  - `inference_providers` InferenceProvidersConfig — Inference provider settings used for LLM calls.
    - `aws` AwsInferenceProviderConfig — Configures AWS Bedrock as the LLM inference provider for this agent or run.
      - `disabled` boolean — If true, opt out of Bedrock at this layer.
      - `role_arn` string — IAM role ARN to assume when calling Bedrock.
      - `region` string — AWS region used for STS when assuming the Bedrock inference role.
  - `memory_stores` MemoryStoreRef[], required — Memory stores attached to this agent. Always present; empty when no stores are attached.
    - `uid` string, required — UID of the memory store.
    - `access` 'read_write' | 'read_only', required — Access level for the store.
    - `instructions` string, required — Instructions for how the agent should use this memory store. Must not be empty.
  - `base_harness` string — Default harness for runs executed by this agent. The precedence order for harness resolution is: 1. The harness specified on the run itself 2. The agent's base harness 3. Oz
  - `harness_auth_secrets` HarnessAuthSecrets — Authentication secrets for third-party harnesses. Only the secret for the harness specified gets injected into the environment.
    - `claude_auth_secret_name` string — Name of a managed secret for Claude Code harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "claude".
    - `codex_auth_secret_name` string — Name of a managed secret for Codex harness authentication. The secret must exist within the caller's personal or team scope. Only applicable when harness type is "codex".

## Other responses

- `400` — Invalid request (empty name, user on multiple teams, or on no team)
- `401` — Authentication required
- `403` — Only human users can manage agents, or plan limit exceeded
- `500` — Internal server error

---

[API](https://skmtc.net/warp/apis/oz-agent-api.md) · [All operations](https://skmtc.net/warp/apis/oz-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/warp/oz-agent-api/versions/97be876c33e3/schema)