@orqo/foundationmodels-agent

Agent runner with AG-UI protocol events, HITL interrupts, and dynamic profiles for Apple Foundation Models.

Install

pnpm add @orqo/foundationmodels-agent

Usage

import { createAgentRunner } from "@orqo/foundationmodels-agent";
import type { AgentTool, AgentModel } from "@orqo/foundationmodels-agent";

// Define a tool the agent can call.
const searchTool: AgentTool = {
  name: "web_search",
  description: "Search the web for current information.",
  inputSchema: {
    type: "object",
    properties: { query: { type: "string" } },
    required: ["query"],
  },
  async execute({ query }) {
    return { results: [`Result for: ${query}`] };
  },
};

// Provide a model adapter (implement AgentModel using @orqo/foundationmodels).
declare const model: AgentModel;

const runner = createAgentRunner({
  model,
  tools: [searchTool],
  maxToolCalls: 5,
});

// Run the agent and consume AG-UI protocol events.
for await (const event of runner.run({ message: "What is the weather in Tokyo?" })) {
  switch (event.type) {
    case "RUN_STARTED":
      console.log("Agent started, runId:", event.runId);
      break;
    case "TEXT_MESSAGE_CONTENT":
      process.stdout.write(event.delta);
      break;
    case "TOOL_CALL_START":
      console.log("\nCalling tool:", event.toolCallName);
      break;
    case "RUN_FINISHED":
      if (event.outcome?.type === "interrupt") {
        // Handle human-in-the-loop approval for sensitive tools.
        console.log("Interrupt — awaiting approval:", event.outcome.interrupts[0]?.id);
      } else {
        console.log("\nDone.");
      }
      break;
    case "RUN_ERROR":
      console.error("Error:", event.message);
      break;
  }
}

Also exports selectToolsByText for dynamic tool filtering and the AgentInvalidEditedArgsError error type.

Author

Cristiano Aredes — sole author and maintainer.

• GitHub: @cristianoaredes
• X: @CristianoAredes
• LinkedIn: Cristiano Aredes

Part of FoundationModels JS.

License

AGPL-3.0-only — see LICENSE. Copyright © 2026 Cristiano Aredes.

Network clause (AGPL §13): modified versions offered as a network service must provide Corresponding Source to users of that service.