FAQ
Is Shiro a thin wrapper around OpenAI?#
No. Provider adapters are one piece. Shiro also owns the run lifecycle: tools, handoffs, approvals, sessions, output validation, and tracing.
Do I need Studio?#
No. The runtime works without it. Use Studio when you need timelines, graphs, tool inspection, approval review, or trace replay while building.
How do I register OpenAI?#
engine.use(new OpenAIPlugin({ apiKey, model: "gpt-5" }));Then set provider: "openai" on the agent. See Providers.
Where should user state live?#
In sessions / memory, keyed by sessionId on execute. Do not mutate
agent definitions per user.
Why is my tool missing from Studio?#
The runner never executed it. Calling the underlying function from application
code bypasses traces. Define a tool() and put it on the agent.
Are tool calls retried automatically?#
Only when you configure safe retry behavior. Mutating tools need idempotency first — see Reliability.
Is approval rejection an error?#
Often it is a normal product outcome. Map ApprovalRejectedError (or equivalent) to a user-
visible “not approved” path instead of a generic 500. See Error Handling.
How do I debug a bad answer?#
Open the trace (or Studio) and check, in order: provider input → tool args → tool result → handoff → approval → memory → output validation.
Does engine.stream() exist?#
High-level run streaming is modeled as runtime events on the event bus / TraceManager.
Providers may expose token stream() separately. See Streaming.