eyeballdocs
Guides

Execute tools from an agent loop

Choose between execution envelopes, canonical output, and framework-native tool-call dispatch.

tools.execute

ts
import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});
const execution = await eyeball.tools.execute("gmail.create_draft", {
  userId: "demo_user",
  input: {
    to: ["guest@example.com"],
    subject: "Draft confirmation",
    body: "Please review before sending.",
  },
  idempotencyKey: "draft:reservation:42",
});
console.log(execution.executionId, execution.status);

Use tools.execute when the application needs the execution ID, status, contract versions, or latency. Mode defaults from the canonical tool annotation; mutation retries should pass one stable idempotencyKey.

tools.run

tools.run waits when necessary, returns only the output, and throws EyeballError when the terminal execution failed.

ts
import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});
const output = await eyeball.tools.run(
  "gmail.search_emails",
  { query: "reservation", pageSize: 5 },
  { userId: "demo_user", pollMs: 250, timeoutMs: 30_000 },
);
console.log(output);

executeToolCalls

The helper is overloaded for Anthropic tool_use blocks and OpenAI function calls. It returns model-native result blocks/messages, derives mutation idempotency from the framework call ID, and converts execution failures into safe tool results.

ts
import { Eyeball, executeToolCalls, type OpenAIToolCall } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});
const bundle = await eyeball.tools.get({
  toolkits: ["gmail"],
  format: "openai",
});
const calls: OpenAIToolCall[] = [{
  id: "call_123",
  type: "function",
  function: {
    name: "gmail__search_emails",
    arguments: JSON.stringify({ query: "reservation" }),
  },
}];
const results = await executeToolCalls(eyeball, calls, {
  userId: "demo_user",
  nameMap: bundle.nameMap,
});
console.log(results);

Framework defaults are anthropic:<tool-use-id> and openai:<tool-call-id>. Dispatch is constrained to the emitted bundle's nameMap; a model cannot invoke a valid catalog tool that was not advertised in that bundle.

See the generated Tools API for every overload, parameter, return type, and normalized failure path.