---
title: Objectives | cadenya
description: Execute agent work and monitor results.
---

Objectives are execution instances. You give a published agent a task — an initial message — and the agent works to complete it, calling tools and reasoning through the problem.

## Lifecycle

Every objective moves through these states:

| State         | Description                                |
| ------------- | ------------------------------------------ |
| **Pending**   | Created, waiting to start execution.       |
| **Running**   | The agent is actively working on the task. |
| **Completed** | The agent finished successfully.           |
| **Failed**    | Execution encountered an error.            |
| **Cancelled** | The objective was manually stopped.        |

## Creating an objective

An objective requires an agent ID and an initial message:

```
const objective = await client.objectives.create({
  agent_id: "agent_01ABC...",
  initial_message:
    "Summarize the key findings from last week's research reports.",
});
```

You can also provide optional parameters:

```
const objective = await client.objectives.create({
  agent_id: "agent_01ABC...",
  initial_message:
    "Summarize the key findings from last week's research reports.",
  variation_id: "agentvar_01XYZ...", // Use a specific variation
  labels: {
    project: "weekly-reports",
  },
  external_id: "my-system-id-123", // For tracking in your system
});
```

If you don’t specify a `variation_id`, the agent’s variation selection mode determines which variation is used.

## Monitoring execution

Once an objective is running, you can monitor it through events, tool calls, and context windows.

### Events

Events provide a stream of what the agent is doing during execution:

```
const events = await client.objectives.events.list(objective.metadata.id);


for (const event of events.data) {
  console.log(event);
}
```

### Tool calls

See every tool the agent invoked, with inputs and outputs:

```
const toolCalls = await client.objectives.toolCalls.list(objective.metadata.id);


for (const call of toolCalls.data) {
  console.log(`${call.tool_name}: ${call.status}`);
}
```

### Execution statistics

The objective itself tracks aggregate statistics:

```
const objective = await client.objectives.retrieve("obj_01ABC...");


console.log(`Input tokens: ${objective.info.total_input_tokens}`);
console.log(`Output tokens: ${objective.info.total_output_tokens}`);
console.log(`Tool calls: ${objective.info.total_tool_calls}`);
console.log(`Context windows: ${objective.info.total_context_windows}`);
```

## Continuing an objective

Completed or failed objectives can be continued with a follow-up message. This resumes execution with the new message appended to the conversation.

```
const event = await client.objectives.continue(objective.metadata.id, {
  message: "Now compare those findings with the previous quarter.",
});
```

This is useful for multi-turn interactions or for recovering from failures by providing additional context.

## Cancelling an objective

Stop a running objective at any time:

```
await client.objectives.cancel(objective.metadata.id, {
  reason: "No longer needed",
});
```

## Feedback

Score an objective to influence how the agent selects variations in the future:

```
await client.objectives.feedback.create(objective.metadata.id, {
  score: 0.8, // -1.0 (worst) to 1.0 (best)
  comment: "Accurate summary, good use of tools",
});
```

Feedback scores are used to improve variation selection over time. Higher-scoring variations are more likely to be selected for future objectives.

Providing feedback is optional but recommended. It helps Cadenya learn which agent configurations work best for your use cases.