---
title: Agents | cadenya
description: Define agent behavior with variations, prompts, and tool assignment.
---

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,
}
```