Agents

An agent has a name and immutable versions. Each version records the agent’s instructions, model, and tool definitions. Chronicle also records runs: what happened each time the agent was invoked. Use a configured SDK client. The examples share that client and the IDs returned by earlier steps.

Methods

Method	HTTP	Does
`agents.register(...)`	`POST /v1/agents/register`	Register a version.
`agents.runs.record(runs)`	`POST /v1/agents/runs/batch`	Record observed runs.
`agents.list()`	`GET /v1/agents`	List agents.
`agents.retrieve(name)`	`GET /v1/agents/{name}`	Read an agent, its versions, and run stats.
`agents.update(name, ...)`	`PATCH /v1/agents/{name}`	Update description, owner, and other metadata.
`agents.chat.start(name)`	`POST /v1/agents/{name}/chat/sessions`	Start a chat session with the current version.
`agents.chat.send(name, session_id, text)`	`POST .../messages`	Send a message.

Registering and recording runs need a key with agents:write. Reads use a platform key.

Before you register

Have your agent code and service tools ready. Registration records a version’s configuration; to execute it in Chronicle, configure its run command and package its dependencies. Use billing-agent@1.0.0 consistently in the examples below and the evaluation guide. Inspect the task it will run: moving ENG-2 and posting the handoff requires actual Linear and Slack tool calls.

Register from your agent code

The simplest way is an adapter that captures the configuration straight from your agent object and records its runs automatically.

Vercel AI SDK
Vercel eve

import { createChronicle } from "@chroniclelabs/ai-sdk";
import { billingAgent } from "./billing-agent.js";

const chronicle = createChronicle({
  apiKey: process.env.CHRONICLE_API_KEY!,
  baseURL: process.env.CHRONICLE_API_URL!,
});

const observed = await chronicle.agents.instrument(billingAgent, {
  name: "billing-agent",
  version: "1.0.0",
  description: "Triages billing incidents across Linear, Salesforce, and Slack.",
});

// Use `observed` from here on so runs are recorded.
await observed.generate({ prompt: "Triage the duplicate invoice on order 7001." });
await chronicle.flush();

agent/hooks/chronicle.ts

import { defineHook } from "eve/hooks";
import { chronicleEveHook } from "@chroniclelabs/eve";

export default defineHook(
  chronicleEveHook({
    apiKey: process.env.CHRONICLE_API_KEY!,
    baseURL: process.env.CHRONICLE_API_URL!,
    agent: { version: "1.0.0" },
  }),
);

Run eve build or eve dev, then use the agent normally.

@chroniclelabs/agentforce observes Salesforce Agentforce agents the same way; those can’t run in evaluations.

Register any agent

For frameworks without an adapter, or from a build pipeline, describe the version yourself. This is what the adapters send under the hood.

Python

version = client.agents.register(
    name="billing-agent",
    version="1.0.0",
    framework="langchain",
    model={"provider": "openai", "id": "gpt-4.1"},
    instructions="Investigate billing incidents, make the requested tool changes, and report the evidence without claiming unverified fixes.",
    tools=[
        {"name": "linear_update_issue", "description": "Update a Linear issue"},
        {"name": "slack_post_message", "description": "Post to a Slack channel"},
    ],
    status="current",
)

const version = await client.agents.register({
  name: "billing-agent",
  version: "1.0.0",
  framework: "langchain",
  model: { provider: "openai", id: "gpt-4.1" },
  instructions: "Investigate billing incidents, make the requested tool changes, and report the evidence without claiming unverified fixes.",
  tools: [
    { name: "linear_update_issue", description: "Update a Linear issue" },
    { name: "slack_post_message", description: "Post to a Slack channel" },
  ],
  status: "current",
});

const version = await client.agents.register({
  name: "billing-agent",
  version: "1.0.0",
  framework: "langchain",
  model: { provider: "openai", id: "gpt-4.1" },
  instructions: "Investigate billing incidents, make the requested tool changes, and report the evidence without claiming unverified fixes.",
  tools: [
    { name: "linear_update_issue", description: "Update a Linear issue" },
    { name: "slack_post_message", description: "Post to a Slack channel" },
  ],
  status: "current",
});

_, err := client.Agents.Register(ctx, chronicle.AgentRegisterParams{
    Name:         "billing-agent",
    Version:      "1.0.0",
    Framework:    "langchain",
    Model:        chronicle.AgentModel{Provider: "openai", ID: "gpt-4.1"},
    Instructions: "Investigate billing incidents, make the requested tool changes, and report the evidence without claiming unverified fixes.",
    Tools: []chronicle.AgentTool{
        {Name: "linear_update_issue", Description: "Update a Linear issue"},
        {Name: "slack_post_message", Description: "Post to a Slack channel"},
    },
    Status: "current",
})
if err != nil {
    return err
}

let version = client.agents().register(AgentRegisterParams {
    name: "billing-agent".into(),
    version: "1.0.0".into(),
    framework: "langchain".into(),
    model: AgentModel { provider: "openai".into(), id: "gpt-4.1".into() },
    instructions: "Investigate billing incidents, make the requested tool changes, and report the evidence without claiming unverified fixes.".into(),
    tools: vec![
        AgentTool { name: "linear_update_issue".into(), description: "Update a Linear issue".into() },
        AgentTool { name: "slack_post_message".into(), description: "Post to a Slack channel".into() },
    ],
    status: Some("current".into()),
    ..Default::default()
}).await?;

Parameter	Meaning
`name`, `version`	The identity. Immutable once registered.
`framework`	A label: `ai-sdk`, `eve`, `langchain`, `openai-agents`, `crewai`, `pydantic-ai`, and others.
`model`, `instructions`, `tools`	What you’re testing. Shown in the dashboard’s Manifest tab and diffed in Changes.
`status`	`current` (default), `stable`, `draft`, or `deprecated`.
`metadata`	Optional: `owner`, `environment`, `purpose`. Editable later with `agents.update`.

Registering the same name and version with identical content is a no-op; with different content it’s a 409. Bump the version when the agent changes. Registering a new current version moves the old one to stable.

Run in an evaluation

Registration does not upload code or configure execution. Package the selected agent version and its dependencies, supply its model credentials, and configure a command that starts its entry point inside the evaluation sandbox. Chronicle sets these variables for each trial:

Variable	Purpose
`INSTRUCTION_PATH`	Read the task instruction from this file.
`WORK_DIR`	Write the final answer to `$WORK_DIR/output.txt`.
`CHRONICLE_AGENT_VERSION`	The selected `name@version`; run the matching code.
`CHRONICLE_TRIAL_ID`	The trial ID for your logs.

For tasks in a world, use the service credentials injected into the trial instead of production credentials. Your HTTP clients must respect HTTP_PROXY, HTTPS_PROXY, and the supplied CA settings (NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE). Standard output and error are captured as diagnostics. A clean exit means the agent finished; attached scorers determine whether it completed the task. See Run an evaluation to configure the test.

Record runs

Adapters do this for you. From your own code, record each invocation after it finishes:

Python

client.agents.runs.record([{
    "run_id": "inv-2026-09-10-001",
    "agent": "billing-agent@1.0.0",
    "started_at": "2026-09-10T14:00:00Z",
    "finished_at": "2026-09-10T14:00:42Z",
    "status": "success",
    "tool_calls": [{"name": "linear_update_issue", "status": "ok", "duration_ms": 310}],
    "usage": {"input_tokens": 4200, "output_tokens": 380},
}])

await client.agents.runs.record([{
  runId: "inv-2026-09-10-001",
  agent: "billing-agent@1.0.0",
  startedAt: "2026-09-10T14:00:00Z",
  finishedAt: "2026-09-10T14:00:42Z",
  status: "success",
  toolCalls: [{ name: "linear_update_issue", status: "ok", durationMs: 310 }],
  usage: { inputTokens: 4200, outputTokens: 380 },
}]);

await client.agents.runs.record([{
  runId: "inv-2026-09-10-001",
  agent: "billing-agent@1.0.0",
  startedAt: "2026-09-10T14:00:00Z",
  finishedAt: "2026-09-10T14:00:42Z",
  status: "success",
  toolCalls: [{ name: "linear_update_issue", status: "ok", durationMs: 310 }],
  usage: { inputTokens: 4200, outputTokens: 380 },
}]);

_, err = client.Agents.Runs.Record(ctx, []chronicle.AgentRun{{
    RunID:      "inv-2026-09-10-001",
    Agent:      "billing-agent@1.0.0",
    StartedAt:  "2026-09-10T14:00:00Z",
    FinishedAt: "2026-09-10T14:00:42Z",
    Status:     "success",
    ToolCalls:  []chronicle.ToolCall{{Name: "linear_update_issue", Status: "ok", DurationMs: 310}},
    Usage:      &chronicle.Usage{InputTokens: 4200, OutputTokens: 380},
}})
if err != nil { return err }

client.agents().runs().record(vec![AgentRun {
    run_id: "inv-2026-09-10-001".into(),
    agent: "billing-agent@1.0.0".into(),
    started_at: "2026-09-10T14:00:00Z".into(),
    finished_at: Some("2026-09-10T14:00:42Z".into()),
    status: "success".into(),
    tool_calls: vec![ToolCall { name: "linear_update_issue".into(), status: "ok".into(), duration_ms: Some(310) }],
    usage: Some(Usage { input_tokens: 4200, output_tokens: 380 }),
    ..Default::default()
}]).await?;

Up to 100 runs per call. A run_id is write-once: send the same body again to retry, use a new ID for a new run.

Read the registry

Python

for agent in client.agents.list().items:
    print(agent.name, agent.current_version)

agent = client.agents.retrieve("billing-agent")
for v in agent.versions:
    print(v.version, v.status, v.model, len(v.tools))
print(agent.runs.count, agent.runs.success_rate)

for (const agent of (await client.agents.list()).items) console.log(agent.name, agent.currentVersion);

const agent = await client.agents.retrieve("billing-agent");
for (const v of agent.versions) console.log(v.version, v.status, v.model, v.tools.length);
console.log(agent.runs.count, agent.runs.successRate);

for (const agent of (await client.agents.list()).items) console.log(agent.name, agent.currentVersion);

const agent = await client.agents.retrieve("billing-agent");
for (const v of agent.versions) console.log(v.version, v.status, v.model, v.tools.length);
console.log(agent.runs.count, agent.runs.successRate);

agents, err := client.Agents.List(ctx)
if err != nil {
    return err
}
for _, a := range agents.Items {
    fmt.Println(a.Name, a.CurrentVersion)
}

agent, err := client.Agents.Retrieve(ctx, "billing-agent")
if err != nil {
    return err
}
for _, v := range agent.Versions {
    fmt.Println(v.Version, v.Status, v.Model, len(v.Tools))
}
fmt.Println(agent.Runs.Count, agent.Runs.SuccessRate)

for a in client.agents().list().await?.items {
    println!("{} {:?}", a.name, a.current_version);
}

let agent = client.agents().retrieve("billing-agent").await?;
for v in &agent.versions {
    println!("{} {:?} {:?} {}", v.version, v.status, v.model, v.tools.len());
}
println!("{} {}", agent.runs.count, agent.runs.success_rate);

Run stats describe observed invocations. Task pass rates come from evaluations.

Chat with an agent

A quick way to confirm Chronicle can run the agent at all. Requires a run command on the agent; see Connect your agent.

Python

session = client.agents.chat.start("billing-agent")
reply = client.agents.chat.send(
    "billing-agent", session.id,
    text="How would you triage a duplicate invoice?",
)
for message in reply.messages:
    print(message.role, message.text)
print(reply.trace_id)

const session = await client.agents.chat.start("billing-agent");
const reply = await client.agents.chat.send("billing-agent", session.id, {
  text: "How would you triage a duplicate invoice?",
});
console.log(reply.messages.at(-1)?.text, reply.traceId);

const session = await client.agents.chat.start("billing-agent");
const reply = await client.agents.chat.send("billing-agent", session.id, {
  text: "How would you triage a duplicate invoice?",
});
console.log(reply.messages.at(-1)?.text, reply.traceId);

session, err := client.Agents.Chat.Start(ctx, "billing-agent")
if err != nil {
    return err
}
reply, err := client.Agents.Chat.Send(ctx, "billing-agent", session.ID, "How would you triage a duplicate invoice?")
if err != nil {
    return err
}
for _, message := range reply.Messages { fmt.Println(message.Role, message.Text) }
fmt.Println(reply.TraceID)

let session = client.agents().chat().start("billing-agent").await?;
let reply = client.agents().chat()
    .send("billing-agent", &session.id, "How would you triage a duplicate invoice?")
    .await?;
println!("{:?} {}", reply.messages.last().map(|m| &m.text), reply.trace_id);

The reply includes the messages so far, tool steps, and a trace_id you can open in Timeline. Chat runs the agent without a world; to test it against a task, run an evaluation.

Get started

Guides

SDKs

Worldsmith endpoints

Methods

Before you register

Register from your agent code

Register any agent

Run in an evaluation

Record runs

Read the registry

Chat with an agent

​Methods

​Before you register

​Register from your agent code

​Register any agent

​Run in an evaluation

​Record runs

​Read the registry

​Chat with an agent

Methods

Before you register

Register from your agent code

Register any agent

Run in an evaluation

Record runs

Read the registry

Chat with an agent