> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Reusable agent configuration endpoints.

An agent is a saved configuration: model, instructions, and tools. It does not run on its own; a [session](/reference/sessions) uses it. Each session copies the agent's settings when it is created, so updating an agent affects only sessions created afterwards. Paths are relative to `/v1`; see the [overview](/reference/overview) for authentication.

## Agents

| Method | Path | Purpose / response |
| - | - | - |
| `GET` | `/agents` | List · `SyncCursorPage[Agent]` |
| `POST` | `/agents` | Create · `Agent` |
| `DELETE` | `/agents/{agent_id}` | Delete · `AgentDeleted` |
| `GET` | `/agents/{agent_id}` | Get · `Agent` |
| `POST` | `/agents/{agent_id}` | Update · `Agent` |

`POST /agents` requires `model`. Optional fields:

| Field | Meaning |
| - | - |
| `name` | A display name |
| `instructions` | The system instructions the model follows |
| `tools` | Function, MCP, and other tool definitions; see [function tools](/guides/function-tools) and [MCP](/guides/mcp) |
| `multi_agent` | `{"enabled": true, "max_concurrent_subagents": n}` to allow [subagents](/guides/subagents) |
| `reasoning`, `text`, `service_tier` | Model settings; support varies by [provider](/providers) |
| `metadata` | Your own key-value labels |

`POST /agents/{agent_id}` updates only the fields you send. `model` is `orca/openrouter/<OpenRouter id>` for Orca credit or `<provider>/<id>` with your own key; any other name is rejected with HTTP 400 on `model`. See [models and provider keys](/providers).

```bash theme={"dark"}
curl -X POST "$BASE_URL/agents" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"model":"orca/openrouter/your-openrouter-model-id","name":"Research helper","instructions":"Be concise."}'
curl -H "Authorization: Bearer $API_KEY" "$BASE_URL/agents?limit=20"
curl -X POST "$BASE_URL/agents/$AGENT_ID" \
  -H "Authorization: Bearer $API_KEY" -H 'Content-Type: application/json' \
  -d '{"instructions":"Cite sources."}'
```

List accepts `after`, `limit`, and `order` (`asc` or `desc`). Delete returns a deletion object. See [Sessions](/reference/sessions) to run an agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.