Objectives

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.