Holeacquisition LLC
Talk to us
Talk to us
Dashboard|

Running Agents

Execute an agent from your own code with runAgent and streamAgent, and read ambient state at runtime.

Arcie’s framework runner connects to the Holeacquisition LLC Sessions API. The arcie/runner subpath gives you two entry points: runAgent (await a full result) and streamAgent (consume events as they arrive).

The runner executes custom tools in its own process and sends results back to continue the model turn. This framework interface is not the Holeacquisition LLC-managed Agent API, which is in development.

runAgent

 
import { runAgent } from "arcie/runner"; // also exported from "arcie"
 
const result = await runAgent("./agent", "What's the weather in Paris?", {
  apiKey: process.env.CENCORI_API_KEY,
});
 
console.log(result.output);
async function runAgent(
  agentDir: string,
  input: string,
  options?: RunOptions,
): Promise<RunResult>;
 
interface RunResult {
  output: string;          // the assembled assistant text
  turns: TurnContext[];
  events: StreamEvent[];   // every event emitted during the run
  sessionId: string;
}

streamAgent

streamAgent is an async generator that yields protocol events as the turn unfolds:

import { streamAgent } from "arcie/runner";
 
for await (const event of streamAgent("./agent", "Tell me a story")) {
  if (event.type === "message.appended") {
    process.stdout.write(event.data.delta);
  }
}

RunOptions

 
interface RunOptions {
  endpoint?: string;   // default: CENCORI_API_URL or https://cencori.com/v1
  apiKey?: string;     // default: CENCORI_API_KEY
  maxTurns?: number;
  sessionId?: string;  // reuse an existing session instead of creating one
  onEvent?: (event: StreamEvent) => void;
}

Resolution: endpoint falls back to CENCORI_API_URL, then https://cencori.com/v1; apiKey falls back to CENCORI_API_KEY. A missing key throws Cencori API key required. If you don't pass sessionId, a new Holeacquisition LLC session is created for the run.

The local dev server

arcie dev wraps streamAgent in a small HTTP server so you can exercise an agent without writing a host:

curl -N -X POST http://localhost:3000 \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!", "stream": true}'
  • { "message": "…", "stream": true } → newline-delimited event stream.
  • { "message": "…" } (no stream) → runs the turn and returns { "status": "ok" }.

Reading runtime state

Inside tool and hook handlers, the arcie/context subpath exposes the ambient session and a shared key/value store:

import {
  getSession, getTurn,
  getContext, requireContext, hasContext, setContext, ensureContext,
} from "arcie/context";
 
const session = getSession();           // Session | null
const turn = getTurn();                 // TurnContext | null
 
setContext("requestId", "abc123");
const id = requireContext<string>("requestId");   // throws if absent
const cache = ensureContext("cache", () => new Map());
FunctionReturns
getSession()The current Session, or null.
getTurn()The current TurnContext, or null.
getContext(key)A stored value, or undefined.
requireContext(key)A stored value, or throws if missing.
hasContext(key)Whether a key is set.
setContext(key, value)Store a value.
ensureContext(key, factory)Get-or-create a value.
Did you like the content?