Agents

Agents are workspace-scoped resources that define how an AI executes work. Each agent contains one or more variations — distinct configurations that specify a system prompt, model, and available tools.

Agent lifecycle

Agents have three statuses:

• Draft — The agent is being configured. It cannot be used in objectives.
• Published — The agent is available for use in objectives.
• Archived — The agent is retired. Existing objectives continue to work, but new objectives cannot use it.

// Create a draft agent
const agent = await client.agents.create({
  name: "Research Agent",
  description: "Researches topics using web tools",
  status: "draft",
});

// Publish when ready
await client.agents.update(agent.metadata.id, {
  status: "published",
});

An agent must be published before you can create objectives against it.

Variations

Variations are the core of agent configuration. Each variation defines a complete set of instructions and capabilities for the agent.

A variation includes:

• System prompt — Instructions that define the agent’s behavior, personality, and constraints. Up to 1MB.
• Model — Which LLM to use and its temperature setting.
• Tool assignment — Which tools, tool sets, or sub-agents are available.
• Constraints — Limits on tool calls and sub-objectives.

Creating a variation

When you create an agent, you can include an initial variation using default_variation:

const agent = await client.agents.create({
  name: "Research Agent",
  description: "Researches topics using web tools",
  status: "published",
  default_variation: {
    name: "v1",
    prompt:
      "You are a research assistant. Find accurate, up-to-date information using the tools available to you. Cite your sources.",
    model_config: {
      model_id: "claude/opus-4.6",
      temperature: 0.3,
    },
    agent_tools: [
      {
        tool_set: {
          tool_set_id: "toolset_01ABC...",
        },
      },
    ],
  },
});

You can also add variations to an existing agent:

const variation = await client.agents.variations.create(agent.metadata.id, {
  name: "v2",
  description: "More creative research style",
  prompt:
    "You are a creative research assistant. Explore unconventional angles and connections.",
  model_config: {
    model_id: "claude/opus-4.6",
    temperature: 0.8,
  },
  agent_tools: [
    {
      tool_set: {
        tool_set_id: "toolset_01ABC...",
      },
    },
  ],
});

Tool assignment

Three types of tools can be assigned to a variation:

Tool sets

Assign an entire tool set. All tools in the set become available to the agent.

agent_tools: [
  {
    tool_set: {
      tool_set_id: "toolset_01ABC...",
    },
  },
];

Individual tools

Assign specific tools from a tool set, rather than the entire set.

agent_tools: [
  {
    tool: {
      tool_id: "tool_01XYZ...",
    },
  },
];

Sub-agents

Assign other agents as sub-agents. The variation can spawn objectives against them during execution.

agent_tools: [
  {
    agent: {
      agent_id: "agent_01DEF...",
    },
  },
];

You can mix all three types in a single variation. For example, assign a tool set for general capabilities, a specific tool for a specialized task, and a sub-agent for delegation.

Model configuration

Each variation specifies which model to use:

• Model ID — In family/model format, e.g., claude/opus-4.6.
• Temperature — Controls randomness, from 0.0 (deterministic) to 1.0 (creative). Defaults vary by model.

model_config: {
  model_id: "claude/opus-4.6",
  temperature: 0.5,
}