Agents API

Agents are project-scoped, versioned resources that package a system prompt, model, tools, fragments, and guardrails. Updating an agent creates a new immutable revision; the agent slug stays stable while current_revision advances.

Agents can be executed directly with the convenience endpoints below or embedded into workflows via agent.run (see Agents Guide).

Quick Reference

GET    /api/v1/projects/:id/agents              List agents
POST   /api/v1/projects/:id/agents              Create an agent
GET    /api/v1/projects/:id/agents/:slug        Get an agent
PATCH  /api/v1/projects/:id/agents/:slug        Update an agent
DELETE /api/v1/projects/:id/agents/:slug        Delete an agent
POST   /api/v1/projects/:id/agents/:slug/run    Run an agent
POST   /api/v1/projects/:id/agents/:slug/test   Test an agent
POST   /api/v1/projects/:id/agents/:slug/replay Replay an agent

Authentication

• Secret key (mr_sk_*) required for CRUD, test, and replay.
• Run accepts either a secret key or a customer bearer token.
• When using a secret key, you can attribute usage to a customer by setting X-ModelRelay-Customer-Id or the customer_id field in the run request.

Agent Resource

Responses include an agent metadata object plus the latest version snapshot:

Create Agent

POST /api/v1/projects/:id/agents

Request Body

Example

curl -X POST https://api.modelrelay.ai/api/v1/projects/123/agents \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Researcher",
    "slug": "researcher",
    "description": "Finds sources and summarizes them",
    "system": "You are a careful researcher.",
    "model": "claude-opus-4-5",
    "tools": [
      {"definition": {"type": "function", "function": {"name": "search", "parameters": {"type": "object", "properties": {"q": {"type": "string"}}}}}}
    ],
    "max_steps": 6,
    "tool_failure_policy": "retry",
    "tool_retry_count": 2
  }'

Update Agent

PATCH /api/v1/projects/:id/agents/:slug

Updates agent metadata and/or configuration. If configuration changes, a new immutable revision is created.

Tool Refs

Each entry in tools is one of:

• Tool definition: Provide a definition (function, image_generation, web, code_execution, etc.).
• Tool hook: Provide hook_id plus a definition to route execution through a tool hook.
• Fragment tool: Provide fragment.ref that matches a fragment name in fragments. Optionally map fragment inputs with fragment.inputs using JSON pointers into the tool arguments.

Example fragment tool:

{
  "fragment": {
    "ref": "research-pipeline",
    "inputs": {
      "query": "/q",
      "filters": ""
    }
  }
}

An empty pointer ("") passes the full tool arguments JSON payload to the fragment input. If no mapping is provided, inputs default to /<inputName>.

Run Agent

POST /api/v1/projects/:id/agents/:slug/run

Runs the agent with the provided input. This endpoint is a convenience wrapper around a workflow containing a single agent.run node.

Request Body

Run Options

Example

curl -X POST https://api.modelrelay.ai/api/v1/projects/123/agents/researcher/run \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "input": [
      {"type": "message", "role": "user", "content": [{"type": "text", "text": "Summarize Q4 sales."}]}
    ],
    "options": {"max_steps": 4, "capture_tool_io": true}
  }'

Response

{
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "output": [{"type": "message", "role": "assistant", "content": [{"type": "text", "text": "..."}]}],
  "usage": {
    "total_steps": 2,
    "total_llm_calls": 2,
    "total_tool_calls": 1,
    "total_input_tokens": 120,
    "total_output_tokens": 260,
    "total_cost_cents": 5
  },
  "steps": []
}

Test Agent

POST /api/v1/projects/:id/agents/:slug/test

Runs the agent with mocked tool outputs. Useful for CI and prompt iteration.

Request Body

mock_tools values can be:

• an array (returned sequentially),
• an object keyed by id or key in tool arguments, or
• a single JSON value (returned once).

Replay Agent

POST /api/v1/projects/:id/agents/:slug/replay

Replays an agent using the same request format as test. Intended for deterministic reruns with mocked tool output.