Solution Design Playbook
How to turn a business request into an agent solution that works: which building blocks you need, how they connect, and where the risks are. It captures how the raia team designs and builds agents for CSI business units.
Where this fits
The Your First Agent lifecycle includes a step called Build blueprint (Scope, step 2). Before anyone configures anything, it asks you to decide what the agent does, what it can reach and what it's allowed to change. This playbook is the guide to that step, and to every later decision that depends on it.
| Resource | The question it answers |
|---|---|
| The 5 Planning Questions | How should this agent behave? Its purpose, audience, tone, guardrails and hand-off rules. |
| This playbook | What system does the agent sit in? Knowledge, live data, actions, workflows and approvals. |
| Product documentation | Where is the setting, and what exactly does it do? |
Who it's for
Start with The mental model and The design process, then read the scenarios for your function. By the end you'll be able to describe a solution clearly enough for someone to build it.
Read the playbook in order. Spend extra time on Knowledge vs live data, Loops and outbound, and the Blueprint checklist.
Focus on Connectors: two jobs, Knowledge vs live data, and the anti-patterns about identity and permissions.
(From Users to Builders to Managers)
Read The mental model, Cost and model choice, and the scenario page for the area you'd start with.
How the playbook is organized
Getting started
- The mental model: The four building blocks and the five questions that decide most designs.
- The design process: Eight steps from the business goal to a tested blueprint.
Building blocks in practice
- Choosing the interface: Where people meet the agent, and when each channel fits.
- Knowledge vs live data: What an agent should learn and what it should fetch.
- Connectors: two jobs: Importing content versus giving agents live access.
- Skills that change the design: Escalation, scoring and summaries, orchestrator, MCP and webhooks.
- Loops and outbound: Workflows that run without being asked, and when to use raia Control.
- Cost and model choice: Matching models to tasks and keeping token spend tied to outcomes.
Patterns and scenarios
- Pattern library: Twelve reusable solution patterns.
- Scenario library: real requests and the designs that fit them, by function: Support, Engineering and product, Sales and marketing, Operations, data and finance, and Events.
Before you launch
- Anti-patterns: Common design mistakes and what to do instead.
- Blueprint checklist: What must be true before a design is ready to build.
- Glossary: The terms used throughout, defined precisely.
Six ideas behind every page
- Start with the smallest design that works. One well-scoped agent beats a fleet of agents. Add a workflow, a second agent or a new channel only when a requirement demands it.
- Learn what's stable, fetch what changes. Manuals, policies and approved procedures belong in knowledge. Account records, open tickets, opportunities and live measurements should be fetched from the source when they're needed.
- Keep audiences apart. When private information is involved, customers and employees need different agents and different knowledge. An internal agent can consult a public one, but never the other way round.
- Make actions narrow, approved and provable. Give an agent only the tools it needs. Put a person in front of unfamiliar or consequential actions at first. Require evidence that something happened, such as a case number or a saved record, rather than the agent's word.
- Write the rules down. Urgency, lead scores and routing are business decisions. Agents need your rubric and real examples, not assumptions.
- Measure outcomes, not just deflection. An abandoned chat can look like a solved one. Track hours returned, drafts, escalations and answer quality alongside resolution rates.