Migration

Move an existing agent loop into Shiro in small, reversible steps.

Migration

You do not need to rewrite everything at once. Move the execution loop first, then fold in tools, sessions, approvals, and traces.

Step 1 — Provider through Shiro#

Keep your model vendor. Install the provider plugin and call engine.execute for one path that used to call the vendor SDK directly.

Success check: one run completes with a runId.

Step 2 — Tools#

Convert direct function calls into tool() definitions with parameters. Attach them to an agent.

Success check: tool spans appear in a trace / Studio.

Step 3 — Sessions#

Pass sessionId for multi-turn users. Stop storing history on the agent object.

Success check: a follow-up question uses prior context without prompt hacking.

Step 4 — Approvals#

Pick one risky tool (refund, delete, deploy). Set requiresApproval: true. Confirm the pause in Studio’s approval center.

Success check: rejection does not execute the side effect.

Step 5 — Always export traces#

Export JSON (or your sink) before large behavior changes. Traces are the baseline for comparing old vs new.

Step 6 — Handoffs last#

Split agents only when tools or policy differ. Register specialists and attach a handoff strategy — see Multi-Agent.

Common mistakes#

  • Migrating every tool in one PR
  • Leaving a “temporary” direct provider call in the hot path
  • Adding Studio only after the first production incident
  • Treating memory as a global cache