Agents

Register the AI agents Chronicle observes. Chronicle does not modify or control your agents - it listens to their actions, evaluates their traces, and generates correction artifacts developers apply on their own.

Installnpm install @chronicle-labs/sdk

SDK generation in progress - until published, Node 18+ fetch works with no extra dependencies.

Endpoints

Method	Path	Status
`POST`	`/v1/agents`	Beta
`GET`	`/v1/agents`	Beta
`GET`	`/v1/agents/{id}`	Beta

The agent object

An agent profile tells Chronicle what it is observing. It stores the agent's identity, goal, instructions the agent should abide by, tools it has access to, and model configuration. This context is attached to every trace the agent produces so Chronicle can evaluate behavior against the agent's intended purpose.

Chronicle is read-only with respect to your agents. It observes actions, evaluates traces, and produces artifacts. You apply those artifacts in your own agent code, prompt, or config.

name - human-readable label for the agent (e.g. "Refund Agent v2").
goal - the agent's primary objective in plain language. Chronicle evaluates traces against this goal.
instructions - rules and guidelines the agent should abide by. Chronicle checks traces against these instructions.
tools - list of tool definitions the agent can call. Each has name, description, and parameter schema.
constraints - known rules the agent should follow (e.g. escalation thresholds). Chronicle checks traces against these.
model - model identifier and configuration (model name, temperature, max tokens).
metadata - arbitrary key-value pairs for versioning, environment tags, or team ownership.

Register an agent

Register an agent profile so Chronicle knows what it is observing. The returned agent_id is referenced when submitting traces. Chronicle uses the goal, instructions, tools, and constraints to evaluate whether the agent's actions are correct.

tenant_idstringrequired

Tenant namespace.

namestringrequired

Human-readable agent name.

goalstringrequired

The agent's primary objective in plain language.

instructionsstring[]

Rules and guidelines the agent should abide by. Chronicle evaluates traces against these.

toolsobject[]

Tool definitions. Each has name, description, and parameters (JSON Schema).

constraintsstring[]

Known rules the agent should follow. Chronicle checks traces against these.

modelobject

Model configuration: name, temperature, max_tokens, and other provider-specific settings.

metadataobject

Arbitrary key-value pairs for versioning, environment, or team tags.

Node

const agent = await chronicle.agents.create({
  tenant_id: "tenant_demo",
  name: "Refund Agent v2",
  goal: "Process customer refund requests according to company policy, escalating when thresholds are exceeded.",
  instructions: [
    "Follow company refund policy strictly",
    "Refunds above $25 require manager approval before processing",
    "Always verify order status before issuing a refund",
  ],
  tools: [
    {
      name: "refund_api.create",
      description: "Issue a refund for an order",
      parameters: { type: "object", properties: { order_id: { type: "string" }, amount: { type: "integer" } }, required: ["order_id", "amount"] },
    },
    {
      name: "escalation_api.request_approval",
      description: "Request manager approval for a high-value action",
      parameters: { type: "object", properties: { order_id: { type: "string" }, amount: { type: "integer" } }, required: ["order_id", "amount"] },
    },
  ],
  constraints: [
    "Refunds above 2500 cents require manager approval before processing",
    "Never issue refunds for orders older than 90 days without manual review",
  ],
  model: { name: "gpt-4o", temperature: 0.1, max_tokens: 2048 },
  metadata: { version: "2.1.0", team: "cx-automation", environment: "staging" },
});

Response

JSON

{
  "agent_id": "agt_01J8YKR4MPNQ7VWXYZ",
  "name": "Refund Agent v2",
  "goal": "Process customer refund requests according to company policy, escalating when thresholds are exceeded.",
  "tools_count": 2,
  "constraints_count": 2,
  "model": { "name": "gpt-4o" },
  "created_at": "2026-02-21T10:00:00Z",
  "updated_at": "2026-02-21T10:00:00Z"
}

List agents

Return all registered agents for a tenant.

tenant_idstringrequired

Tenant namespace.

limitinteger

Max agents to return (default 25, max 1000).

offsetinteger

Number of results to skip (default 0).

Node

const agents = await chronicle.agents.list({ tenant_id: "tenant_demo" });

Response

JSON

{
  "agents": [
    {
      "agent_id": "agt_01J8YKR4MPNQ7VWXYZ",
      "name": "Refund Agent v2",
      "goal": "Process customer refund requests according to company policy, escalating when thresholds are exceeded.",
      "tools_count": 2,
      "constraints_count": 2,
      "model": { "name": "gpt-4o" },
      "created_at": "2026-02-21T10:00:00Z",
      "updated_at": "2026-02-21T10:00:00Z"
    }
  ],
  "count": 1,
  "has_more": false
}

Retrieve an agent

Fetch the full agent profile including goal, instructions, tools, constraints, and model config.

Node

const agent = await chronicle.agents.retrieve("agt_01J8YKR4MPNQ7VWXYZ");

Response

JSON

{
  "agent_id": "agt_01J8YKR4MPNQ7VWXYZ",
  "tenant_id": "tenant_demo",
  "name": "Refund Agent v2",
  "goal": "Process customer refund requests according to company policy, escalating when thresholds are exceeded.",
  "instructions": [
    "Follow company refund policy strictly",
    "Refunds above $25 require manager approval before processing",
    "Always verify order status before issuing a refund"
  ],
  "tools": [
    { "name": "refund_api.create", "description": "Issue a refund for an order", "parameters": { "type": "object", "properties": { "order_id": { "type": "string" }, "amount": { "type": "integer" } } } },
    { "name": "escalation_api.request_approval", "description": "Request manager approval for a high-value action", "parameters": { "type": "object", "properties": { "order_id": { "type": "string" }, "amount": { "type": "integer" } } } }
  ],
  "constraints": [
    "Refunds above 2500 cents require manager approval before processing",
    "Never issue refunds for orders older than 90 days without manual review"
  ],
  "model": { "name": "gpt-4o", "temperature": 0.1, "max_tokens": 2048 },
  "metadata": { "version": "2.1.0", "team": "cx-automation", "environment": "staging" },
  "created_at": "2026-02-21T10:00:00Z",
  "updated_at": "2026-02-21T10:00:00Z"
}

How Chronicle uses agent profiles

Chronicle is an observation layer. It does not modify, call, or control your agents. When a trace is submitted, Chronicle looks up the agent profile to understand the agent's goal, tools, and constraints. It then evaluates the trace against that context to determine whether the agent acted correctly.

When Chronicle generates a correction artifact, the developer reads the artifact and applies the fix in their own codebase - updating the agent's prompt, tool config, or guardrails directly. Chronicle never writes back to your agent.

Register the agent profile with POST /v1/agents.
Submit traces referencing the agent_id.
Chronicle evaluates traces against the agent's goal and constraints.
Correction artifacts describe what should change.
The developer applies the fix in their own agent code or config.
Re-run the simulation to confirm the failure is resolved.