Types Reference

import { defineTool } from "@agentium/core";
import { z } from "zod";

const greetTool = defineTool({
  name: "greet",
  description: "Greet the user by name",
  parameters: z.object({ greeting: z.string() }),
  execute: async (args, ctx) => {
    // Access session info
    console.log("Run ID:", ctx.runId);
    console.log("User:", ctx.userId);
    console.log("Tenant:", ctx.tenantId);

    // Read/write session state
    const visitCount = (ctx.getState<number>("visits") ?? 0) + 1;
    ctx.setState("visits", visitCount);

    // Access metadata
    const source = ctx.metadata.source ?? "unknown";

    // Access dependencies
    const apiUrl = ctx.dependencies.API_URL;

    return `${args.greeting}! Visit #${visitCount} from ${source}`;
  },
});

const agent = new Agent({
  name: "support-bot",
  model: openai("gpt-4o"),
  instructions: (ctx) => {
    const lang = ctx.metadata?.language ?? "English";
    const role = ctx.metadata?.role ?? "customer";
    return `You are a support agent. Respond in ${lang}. User role: ${role}.`;
  },
});

const result = await agent.run("Help me", {
  metadata: { language: "Spanish", role: "admin" },
});

{ role: "user", content: "What is the weather in Tokyo?" }

{
  role: "user",
  content: [
    { type: "text", text: "What's in this image?" },
    { type: "image", data: "https://example.com/photo.jpg" },
  ]
}

{ role: "tool", content: "Tokyo: 22°C, sunny", toolCallId: "call_abc123" }

for await (const chunk of agent.stream("Tell me a story")) {
  switch (chunk.type) {
    case "text":
      process.stdout.write(chunk.text);
      break;
    case "thinking":
      console.log("[thinking]", chunk.text);
      break;
    case "tool_call_start":
      console.log(`Calling tool: ${chunk.toolCall.name}`);
      break;
    case "finish":
      console.log(`\nDone. Tokens: ${chunk.usage?.totalTokens}`);
      break;
  }
}

const controller = new AbortController();
setTimeout(() => controller.abort(), 30_000); // 30s timeout

const result = await agent.run("Summarize this document", {
  sessionId: "session-abc",
  userId: "user-123",
  tenantId: "tenant-acme",
  metadata: { source: "web", priority: "high" },
  apiKey: "sk-user-specific-key",
  signal: controller.signal,
  dependencies: { REPORT_DATE: "2026-02-28" },
});

const agent = new Agent({
  name: "tracked-agent",
  model: openai("gpt-4o"),
  hooks: {
    beforeRun: async (ctx) => {
      console.log(`[${ctx.runId}] Run starting for session ${ctx.sessionId}`);
    },
    afterRun: async (ctx, output) => {
      console.log(`[${ctx.runId}] Done in ${output.durationMs}ms, ${output.usage.totalTokens} tokens`);
    },
    onToolCall: async (ctx, toolName, args) => {
      console.log(`[${ctx.runId}] Calling ${toolName} with`, args);
    },
    onError: async (ctx, error) => {
      console.error(`[${ctx.runId}] Error:`, error.message);
    },
  },
});

const agent = new Agent({
  name: "budget-agent",
  model: openai("gpt-4o"),
  loopHooks: {
    onRoundtripComplete: async (roundtrip, usage) => {
      if (usage.totalTokens > 50_000) {
        console.log("Token budget exceeded, stopping loop");
        return { stop: true };
      }
    },
  },
});

// Pass — input/output is allowed
{ pass: true }

// Fail — input/output is blocked
{ pass: false, reason: "Contains prohibited content" }

const agent = new Agent({
  name: "safe-agent",
  model: openai("gpt-4o"),
  guardrails: {
    input: [
      {
        name: "no-sql-injection",
        validate: async (input) => {
          const text = typeof input === "string" ? input : "";
          if (/DROP\s+TABLE|DELETE\s+FROM/i.test(text)) {
            return { pass: false, reason: "SQL injection detected" };
          }
          return { pass: true };
        },
      },
    ],
    output: [
      {
        name: "no-pii-leak",
        validate: async (output) => {
          if (/\b\d{3}-\d{2}-\d{4}\b/.test(output.text)) {
            return { pass: false, reason: "Output contains SSN" };
          }
          return { pass: true };
        },
      },
    ],
  },
});

const agent = new Agent({
  name: "resilient-agent",
  model: openai("gpt-4o"),
  retry: {
    maxRetries: 5,
    initialDelayMs: 1000,
    maxDelayMs: 30_000,
  },
});

const agent = new Agent({
  name: "careful-agent",
  model: openai("gpt-4o"),
  tools: [deleteTool, readTool],
  approval: {
    policy: ["delete_record"],  // Only require approval for delete
    timeout: 60_000,            // 1 minute
    timeoutAction: "deny",
    onApproval: async (request) => {
      console.log(`Approve ${request.toolName}(${JSON.stringify(request.args)})?`);
      // Your UI/CLI logic here
      return { approved: true };
    },
  },
});

const agent = new Agent({
  name: "sandboxed-agent",
  model: openai("gpt-4o"),
  sandbox: {
    timeout: 10_000,
    maxMemoryMB: 128,
    allowNetwork: false,
    allowFS: { readOnly: ["/data"], readWrite: ["/tmp"] },
    env: { API_KEY: process.env.API_KEY! },
  },
});

import { EventBus } from "@agentium/core";

const eventBus = new EventBus();

eventBus.on("run.start", ({ runId, agentName, input }) => {
  console.log(`[${agentName}] Run ${runId} started: "${input}"`);
});

eventBus.on("tool.call", ({ runId, toolName, args }) => {
  console.log(`[${runId}] Tool: ${toolName}(${JSON.stringify(args)})`);
});

eventBus.on("run.complete", ({ runId, output }) => {
  console.log(`[${runId}] Done: ${output.text.slice(0, 100)}`);
});

eventBus.on("run.error", ({ runId, error }) => {
  console.error(`[${runId}] Error: ${error.message}`);
});

const agent = new Agent({
  name: "my-agent",
  model: openai("gpt-4o"),
  eventBus,
});

// OpenAI o-series
const agent = new Agent({
  model: openai("o3"),
  reasoning: { enabled: true, effort: "high" },
});

// Anthropic
const agent2 = new Agent({
  model: anthropic("claude-sonnet-4-20250514"),
  reasoning: { enabled: true, budgetTokens: 4000 },
});

// Google Gemini
const agent3 = new Agent({
  model: google("gemini-2.5-flash"),
  reasoning: { enabled: true, budgetTokens: 8000 },
});

const agent = new Agent({
  model: openai("gpt-4o"),
  contextCompactor: {
    maxContextTokens: 100_000,
    reserveTokens: 4000,
    strategy: "hybrid",
    summarizeModel: openai("gpt-4o-mini"),
    priorityOrder: ["system", "tools", "recentHistory", "memory"],
  },
});

const agent = new Agent({
  model: openai("gpt-4o"),
  toolResultLimit: {
    maxChars: 20_000,
    strategy: "summarize",
    model: openai("gpt-4o-mini"),
  },
});