apo

Apo — write tasks for your agent

Apo turns "what my agent must be capable of" into an executable spec. A task is a .eval.ts file: fixtures go in, the real agent runs through an adapter, and checks assert the outcome. The result is a verdict — PASS/FAIL with per-check evidence. Read it like test output, fix the agent, rerun.

Vocabulary: a task is the spec of correct behavior; a run is one execution; the verdict is its PASS/FAIL plus the check breakdown; the trace is the tool/generation calls the agent made; deliverables are the structured outputs the adapter collected.

The four pieces

Adapter — the minimal bridge

// e2e/my-adapter.ts
import { defineAdapter, registerApoTracing } from "@apo-ai/sdk/agent-task";
import { z } from "zod";
import { runMyAgent } from "../src/agent"; // your real agent

await registerApoTracing(); // routes the agent's gen_ai.* spans into the run trace

export const myAdapter = defineAdapter({
  name: "my-agent",
  deliverables: { summary: z.string() },
  // What to hand the agent each turn; return null to end the conversation.
  turn: async ({ files, transcript }) =>
    transcript.length > 0 ? null : await files.read("instructions.md"),
  async initialize() {
    return {}; // per-run state, threaded into every later context
  },
  async startSession(ctx) {
    return {
      // report the model your agent actually resolved — apo never picks it
      runConfiguration: { model: process.env.MY_AGENT_MODEL ?? "gpt-4o-mini" },
      async sendUserTurn(turn) {
        const response = await runMyAgent(String(turn));
        return { response };
      },
    };
  },
  async collectDeliverables() {
    return { summary: "what the agent produced" };
  },
});