Engine

The Engine is Shiro’s process-scoped entrypoint. It does not run the agent loop itself. It wires shared services and creates a Runner for each execution.

import { Engine, TraceManager } from "@shiro-sdk/core";
import { OpenAIPlugin } from "@shiro-sdk/openai";

const traces = new TraceManager();
const engine = new Engine({ events: traces });

engine.use(
  new OpenAIPlugin({
    apiKey: process.env.OPENAI_API_KEY!,
    model: "gpt-5",
  })
);

Why it exists#

Without a long-lived engine, every request rebuilds provider clients, plugin state, and registries. Traces stop lining up. Plugins re-run setup. You lose the ability to share one observability pipeline across many runs.

The engine answers: what infrastructure do all runs share?

What it owns#

• Provider registration (typically via plugins)
• Tool and agent registries
• Optional memory / session / approval services
• Event bus used by tracing and Studio
• Lifecycle: Created → Ready → Stopped

engine.execute() activates plugins if needed, ensures the engine is ready, creates a runner, and returns that runner’s result.

Creating and starting#

You usually do not call start() yourself. The first execute() transitions a newly created engine to Ready. Call stop() during process shutdown if you need an explicit teardown.

const result = await engine.execute(agent, "Summarize open invoices for acct_48");

Registering agents#

For multi-agent work, register specialists the handoff strategy can resolve:

engine.registerAgent(billingAgent);
engine.registerAgent(researchAgent);

See Multi-Agent.

What it does not do#

When to create it#

Best practices#

• Install plugins before accepting traffic
• Pass a shared TraceManager (or event bus) into the engine
• Keep credentials in provider / plugin config, not on agents
• Reuse the engine across requests

Common mistakes#

• new Engine() inside every request handler
• Storing the current user on the engine
• Calling OpenAI (or another SDK) directly after registering a Shiro provider
• Expecting Studio to show runs that never went through engine.execute()

Related#

• Runner — per-run execution
• Plugins — how providers and exporters install
• Architecture — system view