Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.litellm-agent-platform.ai/llms.txt

Use this file to discover all available pages before exploring further.

Creates a new agent. The agent persists until deleted. Sessions are created separately from this object — this endpoint only defines the agent’s configuration.

​
Request

POST /api/v1/managed_agents/agents
Headers
HeaderValue
AuthorizationBearer <MASTER_KEY>
Content-Typeapplication/json

​
Body parameters

​
model
string
required
LiteLLM model string for the agent, e.g. anthropic/claude-sonnet-4-6. Passed to the harness as LITELLM_DEFAULT_MODEL.
​
name
string
Human-readable label shown in the web UI. Not required to be unique.
​
prompt
string
System prompt injected at the start of every session. May include <!-- skill:<id> --> markers if skills are attached. Leave empty for a general-purpose agent.
​
harness_id
string
default:"opencode"
Container harness to run in the sandbox pod. One of:
ValueTypeDescription
opencodeAPIopencode in server mode
claude-agent-sdkAPIAnthropic Claude Agent SDK
claude-codeTUIClaude Code CLI with PTY
codexTUIOpenAI Codex CLI with PTY
API harnesses accept structured messages via POST /sessions/{id}/message. TUI harnesses expose a WebSocket PTY instead.
​
requirements
string
pip requirements.txt content. Packages are installed into the sandbox at harness boot. Stored as the AGENT_REQUIREMENTS env var internally.
​
repo_url
string
HTTPS URL of a Git repository to clone into the sandbox at session start, e.g. https://github.com/org/repo. Must be a valid URL.
​
branch
string
default:"main"
Branch to check out from repo_url.
​
mcp_servers
string[]
List of MCP server connection strings passed to the harness.
​
allow_out
string[]
Allowed outbound domains for the sandbox network policy. An empty list means no domain-level allow rule is applied.
​
deny_out
string[]
Blocked outbound domains for the sandbox network policy.
​
env_vars
object
Agent-level environment variables persisted to the database and injected into every session container. Use for long-lived secrets such as GITHUB_TOKEN or API keys the agent always needs.Per-session env_vars (set when creating a session) take precedence over agent-level values for the same key.Constraints:
  • Key names must match ^[A-Za-z_][A-Za-z0-9_]*$
  • Maximum 50 keys
  • Total JSON-encoded size must be ≤ 16 KB
  • The following keys are reserved and cause a 400 if used: REPO_URL, BRANCH, LITELLM_API_KEY, LITELLM_API_BASE, LITELLM_DEFAULT_MODEL, AGENT_PROMPT, PORT, GIT_TOKEN, AGENT_REQUIREMENTS
GIT_TOKEN is reserved because the harness entrypoint erases it after git clone so the agent can’t read it back. For tokens that need to survive into the agent shell (for gh pr create, git push, etc.), use GITHUB_TOKEN or GH_TOKEN instead.
​
skill_ids
string[]
IDs of existing skills to attach to the agent at create time. Each skill’s content is appended to prompt as a <!-- skill:<id> --> block. Unknown or unowned skill IDs return 404.
​
sandbox_files
array
Files injected into the sandbox container at session start. Maximum 20 files; total base64-encoded size must be ≤ 10 MB.Each entry has:
FieldTypeDescription
namestringFriendly display name
sandbox_pathstringAbsolute or home-relative path in the container, must start with / or ~
contentstringBase64-encoded file content
content_typestringMIME type, defaults to application/octet-stream
sizenumberFile size in bytes

​
Response

Returns the newly created ApiAgent object. See List agents for the full field reference.

​
Example

curl -X POST "https://<your-platform-host>/api/v1/managed_agents/agents" \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pr-reviewer",
    "model": "anthropic/claude-sonnet-4-6",
    "prompt": "You are a senior engineer who reviews pull requests.",
    "harness_id": "claude-agent-sdk",
    "repo_url": "https://github.com/BerriAI/litellm",
    "branch": "main",
    "env_vars": {
      "GITHUB_TOKEN": "ghp_..."
    }
  }'

{
  "id": "agt_01j9xyz",
  "name": "pr-reviewer",
  "model": "anthropic/claude-sonnet-4-6",
  "prompt": "You are a senior engineer who reviews pull requests.",
  "harness_id": "claude-agent-sdk",
  "supports_tui": false,
  "repo_url": "https://github.com/BerriAI/litellm",
  "branch": "main",
  "pfp_url": null,
  "mcp_servers": [],
  "env_vars": {
    "GITHUB_TOKEN": "ghp_..."
  },
  "attached_skill_ids": [],
  "allow_out": [],
  "deny_out": [],
  "created_at": "2025-05-01T12:00:00.000Z"
}