Quick Start

Engine, plugin, tool, agent, execute — and what the runner does with them.

Quick Start

This walkthrough creates one agent with one tool. The goal is to see how Shiro moves a run through the runtime — not to ship a full product.

1. Engine + provider plugin#

The engine owns shared services. Providers are installed as plugins.

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",
  })
);

2. Define a tool#

Tools need a name, a schema with .parse(), and execute. The model may request the tool; the runner executes it.

import { tool } from "@shiro-sdk/core";
import { z } from "zod";

const weather = tool({
  name: "weather",
  description: "Look up current weather for a city.",
  parameters: z.object({
    city: z.string(),
  }),
  execute: async ({ city }) => ({
    city,
    summary: "Clear",
    temperatureC: 27,
  }),
});

3. Define an agent#

Agents are declarative. Always set provider to a registered provider id or instance.

import { Agent } from "@shiro-sdk/core";

const agent = new Agent({
  name: "support",
  instructions: "Answer briefly. Use the weather tool when the user asks about conditions.",
  provider: "openai",
  tools: [weather],
});

4. Execute#

const result = await engine.execute(agent, "Should I bring an umbrella in Pune today?");

console.log(result.output);
console.log(result.runId);

What happens#

  1. The engine becomes ready and creates a runner
  2. The runner prepares context (session/memory if configured)
  3. The provider receives instructions + messages
  4. The model may request weather with { city: "Pune" }
  5. Shiro validates arguments, executes the tool, and records the span
  6. The provider may be called again with the tool result
  7. The final output returns on result
  8. Events flow through TraceManager for export / Studio
execute → runner → provider → tool → provider → output
                         │
                         └─► events / traces

5. Export a trace (optional)#

import { JsonTraceExporter } from "@shiro-sdk/core";

const json = await traces.export(new JsonTraceExporter());
console.log(json);

Open the export in Studio, or attach it to an issue. See Tracing.

Best practices#

  • Keep the engine outside request handlers
  • Keep tool schemas aligned with execute input types
  • Add tracing before you add a second agent
  • Pass sessionId when the conversation spans requests

Common mistakes#

  • Calling weather.execute yourself — the runner will not see it
  • Forgetting parameters on tool()
  • Omitting provider on Agent
  • Recreating the engine every call

Next#