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 agents start with their initial version in production. Publishing another version does not change production until you promote it.

All endpoints use x-api-key authentication.

Create an agent

POST /v1/agents

Creates an agent and its initial version.

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

{
  "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

{
  "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.

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.

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. Production sessions continue using the current production version until the new version is promoted.

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.

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.

Promote a version to production

PUT /v1/agents/{agentId}/production

Moves the agent’s production pointer to an existing version. Existing production sessions resolve this pointer before sandbox acquisition, so an older session cannot switch the subject’s sandbox back to a pre-promotion configuration. Playground preview sessions remain pinned to the version they are testing.

curl -X PUT "https://api.herm.run/v1/agents/agent_123/production" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HERM_API_KEY" \
  -d '{
    "version": 4
  }'

Field	Type	Required	Description
version	integer	Yes	Existing version number belonging to this agent.

{
  "label": "production",
  "version": 4,
  "agentVersionId": "version_456"
}

Use the same endpoint with an older version number to roll production back.

Manage development tags

Development tags are mutable names for testing a specific immutable version without changing production:

curl -X PUT "https://api.herm.run/v1/agents/agent_123/tags/feature-x" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $HERM_API_KEY" \
  -d '{ "version": 4 }'

Calling PUT again moves the tag. Existing tagged sessions remain pinned to the version they started with; only new sessions resolve the moved pointer. Tag names must start with a lowercase letter and contain only lowercase letters, numbers, or hyphens. production, preview, and latest are reserved.

List and remove tags with:

GET /v1/agents/{agentId}/tags
DELETE /v1/agents/{agentId}/tags/{tagName}

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.

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

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.

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.

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.
PUT	/v1/agents/{agentId}/production	Promote or roll back the production version.
GET	/v1/agents/{agentId}/tags	List development tags.
PUT	/v1/agents/{agentId}/tags/{tagName}	Create or move a development tag.
DELETE	/v1/agents/{agentId}/tags/{tagName}	Remove a development tag.
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.