Installation

Install the core runtime and the OpenAI provider package.

pnpm add @shiro-sdk/core @shiro-sdk/openai zod

zod is commonly used for tool parameters and structured output schemas because it exposes a .parse() method Shiro can call.

Packages#

The npm name shiro (unscoped) is not this project. Always use @shiro-sdk/cli. Do not add @shiro-sdk/studio to your app — Studio is launched by the CLI.

Environment#

Keep credentials out of agent files.

export OPENAI_API_KEY=...

Verify the install#

Create an engine, install the OpenAI plugin, define an agent with a provider id, execute once.

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

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

const agent = new Agent({
  name: "hello",
  instructions: "Answer in one short sentence.",
  provider: "openai",
});

const result = await engine.execute(agent, "What does the Shiro engine own?");
console.log(result.output);

If this throws on missing API keys or provider registration, fix configuration before adding tools or Studio.

Scaffold with the CLI#

pnpm dlx @shiro-sdk/cli init my-agent
cd my-agent
pnpm dev
pnpm studio

shiro init creates the project and writes .env (prompts for the provider API key). shiro dev / pnpm studio runs diagnostics and launches Studio. See CLI.

Monorepo contributors#

From a clone of this repository:

pnpm install
pnpm build
pnpm --filter @shiro-sdk/example-basic-agent start

Common mistakes#

• Installing @shiro-sdk/openai but never calling engine.use(new OpenAIPlugin(...))
• Creating an agent without provider
• Reading secrets from source files committed to git
• Creating a new engine on every request — see Engine
• Using pnpm dlx shiro instead of pnpm dlx @shiro-sdk/cli

Next#

• Quick Start
• CLI