> ## Documentation Index > Fetch the complete documentation index at: https://docs.herm.run/llms.txt > Use this file to discover all available pages before exploring further. # Agents > Create, update, version, and archive reusable agent definitions. An agent is a reusable, versioned configuration. Each version stores its model, system prompt, skills, tools, and metadata. New sessions record the latest version at creation time. All endpoints use `x-api-key` authentication. ## Create an agent ``` POST /v1/agents ``` Creates an agent and its initial version. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST "https://api.herm.run/v1/agents" \ -H "Content-Type: application/json" \ -H "x-api-key: $HERM_API_KEY" \ -d '{ "name": "Acme Creative Agent", "modelName": "openai/gpt-4o-mini", "systemPrompt": "Help Acme plan and execute media workflows.", "skills": [], "tools": [], "roles": [], "mcpServers": [], "rateLimits": { "conversationsPerMinute": 5, "messagesPerMinute": 100 }, "metadata": { "productArea": "media-generation" } }' ``` ### Request body | Field | Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | Human-readable agent name. | | `modelName` | string | Yes | Provider and model name, such as `openai/gpt-4o-mini`. | | `systemPrompt` | string | Yes | System instructions for the agent. | | `skills` | object\[] | Yes | Configured Markdown skills available to the agent version. Each item has `name` and `content`. See [Skills](/api-reference/skills). Use `[]` if none. | | `tools` | object\[] | Yes | Built-in toolset, MCP toolset, and custom tool configuration. Use `[]` if none. | | `roles` | object\[] | No | Named role-specific tool policies. Defaults to `[]`. Sessions can opt into one with `role`. | | `mcpServers` | object\[] | No | MCP server connections available to MCP toolsets. Defaults to `[]`. | | `rateLimits` | object | No | Per-user limits for this agent. `conversationsPerMinute` accepts an integer from 1 through 300; `messagesPerMinute` accepts an integer from 1 through 1,000. Omitted fields default to 5 and 100, respectively. | | `metadata` | object | No | String-keyed metadata values for your own tracking. | Tool objects can be built-in toolsets, MCP toolsets, or custom tools. See [Tools](/api-reference/tools) for full details. Role objects use this shape: | Field | Type | Required | Description | | ------------- | --------- | -------- | ----------------------------------------------------------- | | `name` | string | Yes | Role name passed to `POST /v1/sessions` as `role`. | | `description` | string | No | Human-readable explanation for the role. | | `tools` | object\[] | Yes | Tool configuration used when a session runs with this role. | When a session specifies a role, that role's `tools` replace the agent version's top-level `tools` for approval decisions. Sessions without a role use the version's top-level `tools`. Custom tools use this shape: | Field | Type | Required | Description | | -------------- | ------- | -------- | ------------------------------------- | | `type` | string | Yes | Must be `custom_tool`. | | `name` | string | Yes | Tool name. | | `description` | string | Yes | Tool description for the agent. | | `input_schema` | object | Yes | JSON-schema-like object input schema. | | `enabled` | boolean | No | Defaults to `true`. | Example custom tool: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "type": "custom_tool", "name": "check_order_status", "description": "Look up an order by ID.", "input_schema": { "type": "object", "properties": { "order_id": { "type": "string", "description": "Customer order ID" } }, "required": ["order_id"], "additionalProperties": false }, "enabled": true } ``` ### Response ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": "agent_123", "name": "Acme Creative Agent", "status": "active", "metadata": { "productArea": "media-generation" }, "createdAt": "2026-06-20T23:12:04.746Z", "updatedAt": "2026-06-20T23:12:04.746Z", "rateLimits": { "conversationsPerMinute": 5, "messagesPerMinute": 100 }, "version": { "id": "version_123", "version": 0, "modelName": "openai/gpt-4o-mini", "systemPrompt": "Help Acme plan and execute media workflows.", "skills": [], "roles": [], "mcpServers": [], "metadata": { "productArea": "media-generation" }, "createdAt": "2026-06-20T23:12:04.746Z" }, "tools": [ { "type": "agent_toolset", "defaultConfig": { "enabled": true, "permissionPolicy": { "type": "always_ask" } }, "configs": [] } ] } ``` Agent list, get, create, update, and rate-limit update responses include `rateLimits`. ## List agents ``` GET /v1/agents ``` Returns agents owned by the API key's organization, newest first. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl "https://api.herm.run/v1/agents?limit=20&offset=0" \ -H "x-api-key: $HERM_API_KEY" ``` | Query | Type | Description | | -------- | ------- | ------------------------------------------------------------- | | `limit` | integer | Page size, 1 to 100. Defaults to `50`. | | `offset` | integer | Offset for pagination. Defaults to `0`. | | `status` | string | Optional agent status filter, such as `active` or `archived`. | ## Get an agent ``` GET /v1/agents/{agentId} ``` Returns the latest agent definition and version. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl "https://api.herm.run/v1/agents/agent_123" \ -H "x-api-key: $HERM_API_KEY" ``` ## Update an agent ``` POST /v1/agents/{agentId} ``` Fully replaces the agent configuration and always creates a new immutable agent version. Use this method when removing skills or tools. New sessions always use the latest version and cannot select a historical one. Existing session records retain the version selected when they were created. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST "https://api.herm.run/v1/agents/agent_123" \ -H "Content-Type: application/json" \ -H "x-api-key: $HERM_API_KEY" \ -d '{ "name": "Acme Creative Agent v2", "modelName": "openai/gpt-4o-mini", "systemPrompt": "Answer in one concise sentence.", "skills": [], "tools": [], "mcpServers": [], "metadata": { "revision": "v2" } }' ``` ## Partially update an agent ``` PATCH /v1/agents/{agentId} ``` Publishes a new immutable version while preserving omitted configuration. Collection entries are upserted instead of replacing the whole collection. This lets you update one skill or tool without fetching and resending every other entry. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X PATCH "https://api.herm.run/v1/agents/agent_123" \ -H "Content-Type: application/json" \ -H "x-api-key: $HERM_API_KEY" \ -d '{ "skills": [ { "name": "customer-support", "content": "# Customer Support\n\nUse the updated escalation policy." } ], "expectedVersion": 3 }' ``` The patch may contain `name`, `modelName`, `systemPrompt`, `skills`, `tools`, `roles`, `mcpServers`, `metadata`, and `expectedVersion`. At least one field other than `expectedVersion` is required. | Collection | Matching identity | | ------------ | ------------------------------------------------------------------------ | | `skills` | `name` | | `tools` | `type` plus `name` for custom tools, or `mcpServerName` for MCP toolsets | | `roles` | `name` | | `mcpServers` | `name` | A matching entry is replaced with the supplied object. An entry with a new identity is appended, and all entries not included in the request are preserved. Passing an empty collection does not remove existing entries; use the full `POST` update when you intend to remove skills or tools. `expectedVersion` is optional. When provided, it must equal the current version or the request returns `409 conflict`. When omitted, the gateway protects the version it read while applying the patch, so a concurrent update also returns `409` instead of overwriting changes. The response is the full agent representation with the newly created version. ## Update per-user rate limits ``` PATCH /v1/agents/{agentId}/rate-limits ``` Updates mutable operational policy without creating a new agent version. The change applies immediately to every version and existing session for the agent. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X PATCH "https://api.herm.run/v1/agents/agent_123/rate-limits" \ -H "Content-Type: application/json" \ -H "x-api-key: $HERM_API_KEY" \ -d '{ "conversationsPerMinute": 10, "messagesPerMinute": 200 }' ``` At least one field is required. Conversation limits accept integers from 1 through 300; user-event limits accept integers from 1 through 1,000. The response is the full agent representation. See [Rate limits](/api-reference/rate-limits) for scoping, counting, headers, and error behavior. ## Archive an agent ``` POST /v1/agents/{agentId}/archive ``` Archives the agent. New sessions cannot be created from archived agents. Existing sessions remain accessible. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST "https://api.herm.run/v1/agents/agent_123/archive" \ -H "x-api-key: $HERM_API_KEY" ``` ## List versions ``` GET /v1/agents/{agentId}/versions ``` Returns the version history for an agent, newest first. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl "https://api.herm.run/v1/agents/agent_123/versions?limit=20&offset=0" \ -H "x-api-key: $HERM_API_KEY" ``` ## Get a version ``` GET /v1/agents/{agentId}/versions/{version} ``` Returns a historical agent version by version number. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl "https://api.herm.run/v1/agents/agent_123/versions/1" \ -H "x-api-key: $HERM_API_KEY" ``` ## Endpoint summary | Method | Path | Description | | ------- | ----------------------------------------- | --------------------------------------------------- | | `POST` | `/v1/agents` | Create an agent and initial version. | | `GET` | `/v1/agents` | List agents. | | `GET` | `/v1/agents/{agentId}` | Retrieve an agent's latest version. | | `POST` | `/v1/agents/{agentId}` | Fully replace an agent and create a new version. | | `PATCH` | `/v1/agents/{agentId}` | Partially update an agent and create a new version. | | `PATCH` | `/v1/agents/{agentId}/rate-limits` | Update per-user limits without creating a version. | | `POST` | `/v1/agents/{agentId}/archive` | Archive an agent. | | `GET` | `/v1/agents/{agentId}/versions` | List versions. | | `GET` | `/v1/agents/{agentId}/versions/{version}` | Retrieve a version. |