Agents - Herm

An agent is a reusable, versioned configuration that defines how your agent behaves. It bundles the model, instructions, built-in tools, MCP servers, configured skills, and metadata that shape every session created from it. Create an agent once and reference it by ID each time you create a session. Pass userId when creating a session to give that agent persistent memory and learned skills for the person, organization, workspace, team, or other subject you choose. Runtime deployment is handled by Herm internally. All examples use the Herm SDK:

import Herm from "herm";

const herm = new Herm(); // reads PRISM_API_KEY

Create an agent

POST /v1/agents

Create a reusable agent definition. This does not bind the agent to a customer or start work; create a session when a user is ready to chat.

const agent = await herm.agents.create({
  name: "Acme Creative Agent",
  model: "anthropic/claude-sonnet-4.5",
  instructions:
    "You are Acme's media generation agent. Help the user plan, create, and iterate on high-performing short-form videos.",
  mcpServers: [
    {
      type: "url",
      name: "prism-media",
      url: "https://api.prismvideos.com/mcp",
    },
  ],
  tools: [
    {
      type: "agent_toolset",
      defaultConfig: {
        permissionPolicy: { type: "always_allow" },
      },
      configs: [
        {
          name: "shell",
          permissionPolicy: { type: "always_ask" },
        },
      ],
    },
    {
      type: "mcp_toolset",
      mcpServerName: "prism-media",
      defaultConfig: {
        permissionPolicy: { type: "always_ask" },
      },
    },
  ],
  skills: [
    {
      name: "storyboarding",
      source: "inline",
      content:
        "---\nname: storyboarding\ndescription: Create shot-by-shot storyboards for short-form videos\n---\n# Storyboarding\n...",
    },
  ],
  metadata: {
    productArea: "media-generation",
  },
});

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Human-readable agent name
`model`	string	Yes	Model in `provider/model` form, such as `anthropic/claude-sonnet-4.5`
`instructions`	string	No	System instructions that define behavior and persona
`tools`	array	No	Built-in and MCP toolsets available to the agent — see Tools
`mcpServers`	array	No	MCP servers this agent can connect to — see MCP servers
`skills`	array	No	Configured skill files that teach the agent your domain playbooks — see Skills
`metadata`	object	No	Arbitrary key-value pairs for your own tracking

Tools

Tools are versioned as part of the agent definition. Permission policies control whether Herm executes server-side tools automatically or pauses for approval.

Field	Type	Required	Description
`type`	string	Yes	`agent_toolset` for built-in tools or `mcp_toolset` for one MCP server
`mcpServerName`	string	MCP only	Name of the MCP server this toolset uses
`defaultConfig`	object	No	Default permission policy for every tool in the toolset
`configs`	array	No	Per-tool permission policy overrides

Permission policies are:

Policy	Behavior
`always_allow`	The tool executes automatically
`always_ask`	The session pauses and waits for a tool confirmation event

Permission policies govern server-executed built-in tools and MCP tools. Custom tools executed by your application are controlled by your application.

MCP servers

Field	Type	Required	Description
`type`	string	Yes	Currently `url`
`name`	string	Yes	Unique server name within the agent
`url`	string	Yes	URL of your MCP server

The mcpServerName on an mcp_toolset must match a name in mcpServers.

Skills

Configured skills are part of the versioned agent definition. Learned skills are created by the agent during use and are scoped separately to agentId + userId; see Skills. Each configured skill is loaded from one of three sources:

`source`	Required fields	Description
`file`	`name`, `path`	A `SKILL.md` file uploaded to the agent workspace
`inline`	`name`, `content`	Skill markdown provided directly in the request
`url`	`name`, `url`	A `SKILL.md` fetched from a public URL

Response

{
  "id": "agent_7xK9s2",
  "type": "agent",
  "name": "Acme Creative Agent",
  "model": "anthropic/claude-sonnet-4.5",
  "instructions": "You are Acme's media generation agent.",
  "tools": [],
  "mcpServers": [],
  "skills": [],
  "metadata": {},
  "version": 1,
  "createdAt": "2026-06-11T18:21:09Z",
  "updatedAt": "2026-06-11T18:21:09Z",
  "archivedAt": null
}

Get an agent

GET /v1/agents/:agent_id

Returns the latest agent definition and current version.

const agent = await herm.agents.get("agent_7xK9s2");

console.log(agent.version); // 1

List agents

GET /v1/agents

Returns agents owned by your API key, newest first.

const { data, nextCursor } = await herm.agents.list({ limit: 20 });

Parameter	Type	Required	Description
`limit`	integer	No	Page size, from 1 to 100. Defaults to 20
`cursor`	string	No	Pagination cursor from a previous response

Update an agent

PATCH /v1/agents/:agent_id

Updates an agent definition. If the configuration changes, Herm creates a new agent version. Existing sessions remain pinned to the version they started with; new sessions use the latest version unless you explicitly pin one.

const updated = await herm.agents.update("agent_7xK9s2", {
  version: agent.version,
  instructions:
    "You are Acme's media generation agent. Always propose three creative directions before generating.",
  skills: [
    {
      name: "storyboarding",
      source: "url",
      url: "https://acme.com/skills/storyboarding/SKILL.md",
    },
  ],
});

Pass the current version to prevent concurrent overwrites. Update semantics:

Omitted fields are preserved.
Scalar fields (name, model, instructions) are replaced.
Array fields (tools, mcpServers, skills) are fully replaced; pass an empty array to clear one.
metadata is merged at the key level; set a key to an empty string to delete it.
No-op updates return the existing version.

List versions

GET /v1/agents/:agent_id/versions

Returns the full version history for an agent.

for await (const version of herm.agents.versions.list("agent_7xK9s2")) {
  console.log(`Version ${version.version}: ${version.updatedAt}`);
}

Get a version

GET /v1/agents/:agent_id/versions/:version

Returns a specific historical agent version.

Archive an agent

POST /v1/agents/:agent_id/archive

Archives the agent and makes it read-only. New sessions cannot reference it, but existing sessions continue to run.

const archived = await herm.agents.archive("agent_7xK9s2");

console.log(archived.archivedAt);

Endpoint summary

POST /v1/agents - Create a reusable, versioned agent definition with model, instructions, configured tools, MCP servers, skills, and metadata. GET /v1/agents - List agents. GET /v1/agents/ - Retrieve the latest agent definition, including configured tools, MCP servers, skills, metadata, and current version. PATCH /v1/agents/ - Update an agent definition and create a new version when configuration changes. GET /v1/agents//versions - List the version history for an agent. GET /v1/agents//versions/ - Retrieve a specific historical agent version. POST /v1/agents//archive - Archive an agent so new sessions cannot be created from it while existing sessions continue.

Errors

Status	Error	When
400	`validation_error`	Invalid request body
401	`unauthorized`	Missing or invalid API key
404	`not_found`	Agent or version does not exist
409	`version_conflict`	Update version does not match latest
422	`invalid_skill`	Skill content could not be loaded or parsed

See Errors for the full error reference.

​Create an agent

​Parameters

​Tools

​MCP servers

​Skills

​Response

​Get an agent

​List agents

​Update an agent

​List versions

​Get a version

​Archive an agent

​Endpoint summary

​Errors