Shiro

Shiro is a TypeScript runtime for agent execution. Your application defines agents, tools, and policies. Shiro owns the loop that decides when to call a provider, execute a tool, pause for approval, switch agents, read memory, validate output, and emit trace events.

That split is the whole product. If the execution loop lives in your route handlers, every new concern — timeout, handoff, approval, memory, debugging — becomes another ad-hoc branch. Shiro keeps those transitions in one place so a run can be inspected and replayed.

What Shiro owns#

Mental model#

Engine  ──creates──►  Runner
                        │
                        ├─► Provider call
                        ├─► Tool execution
                        ├─► Approval pause
                        ├─► Handoff
                        ├─► Memory read / write
                        ├─► Output validation
                        └─► Trace / events ──► Studio

The Engine is process-scoped. The Runner is run-scoped. Agents are configuration, not executors. Studio observes the same events the runtime emits; it does not orchestrate the run.

When to use Shiro#

Use Shiro when a single provider call is not enough:

• tools that must be timed, approved, or traced
• sessions that span requests
• handoffs between domain agents
• structured output another system will consume
• runs you expect to debug later

If you only need one completion with no tools or durable state, call the provider directly.

How to read these docs#

1. Installation and Quick Start to run something
2. Mental Model and Architecture to learn the shape
3. Concept pages (Engine, Runner, Tools, …) when you add that concern
4. Studio and Tracing when you need to see what happened
5. Examples for concrete workflow patterns

What these docs avoid#

Marketing adjectives. Every page should explain concrete behavior: what owns what, when to use it, and which mistakes waste the most time.