> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goguava.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Guava Architecture Overview
> How Guava's Dialog System and your Expert work together on every call
export const ExpertAnimation = () => {
const VIEWBOX_WIDTH = 840;
const VIEWBOX_HEIGHT = 220;
const GAP = 24;
const MESSAGE_WIDTH = 210;
const MESSAGE_PADDING_X = 12;
const MESSAGE_RADIUS = 9;
const NIB_WIDTH = 10;
const NIB_HEIGHT = 12;
const ANIMATION_DURATION = 14;
const CALLER_CENTER_X = 50;
const CALLER_HEAD_Y = 85;
const CALLER_HEAD_RADIUS = 17;
const CALLER_BODY_HALF_WIDTH = 29;
const CALLER_NECK_GAP = 4;
const CALLER_BODY_HEIGHT = 36;
const CALLER_BODY_TOP_Y = CALLER_HEAD_Y + CALLER_HEAD_RADIUS + CALLER_NECK_GAP;
const CALLER_BODY_BOTTOM_Y = CALLER_BODY_TOP_Y + CALLER_BODY_HEIGHT;
const CALLER_LABEL_Y = CALLER_BODY_BOTTOM_Y + 24;
const CALLER_RIGHT_EDGE = CALLER_CENTER_X + CALLER_BODY_HALF_WIDTH;
const LEFT_MESSAGE_X = CALLER_RIGHT_EDGE + GAP;
const ACTOR_WIDTH = 112;
const ACTOR_HEIGHT = 120;
const ACTOR_Y = (VIEWBOX_HEIGHT - ACTOR_HEIGHT) / 2;
const ACTOR_RADIUS = 8;
const ACTOR_LABEL_FONT_SIZE = 10;
const ACTOR_LABEL_Y = (VIEWBOX_HEIGHT + ACTOR_LABEL_FONT_SIZE) / 2;
const DIALOG_ENGINE_X = LEFT_MESSAGE_X + MESSAGE_WIDTH + GAP;
const RIGHT_MESSAGE_X = DIALOG_ENGINE_X + ACTOR_WIDTH + GAP;
const EXPERT_X = RIGHT_MESSAGE_X + MESSAGE_WIDTH + GAP;
const MESSAGES_START_Y = 43;
const MESSAGE_X = {
left: LEFT_MESSAGE_X,
right: RIGHT_MESSAGE_X
};
const MESSAGE_FILL = {
primary: "rgba(26,147,254,0.14)",
secondary: "rgba(255,255,255,0.08)"
};
const MESSAGE_STROKE = {
primary: "rgba(26,147,254,0.45)",
secondary: "rgba(255,255,255,0.22)"
};
const animationSecs = seconds => seconds / ANIMATION_DURATION * 100;
const messageAnimation = (name, hiddenUntil) => {
const hiddenStop = hiddenUntil === 0 ? "0%" : `0%, ${animationSecs(hiddenUntil)}%`;
const visibleAt = animationSecs(hiddenUntil + 0.4);
return `
@keyframes ${name} {
${hiddenStop} { opacity: 0; transform: translateY(6px) scale(0.98); }
${visibleAt}% { opacity: 1; transform: translateY(0px) scale(1); }
90% { opacity: 1; transform: translateY(0px) scale(1); }
97%, 100% { opacity: 0; transform: translateY(-4px) scale(0.98); }
}
.${name} { animation: ${name} ${ANIMATION_DURATION}s ease-in-out infinite; }
`;
};
const Lines = ({x, lines}) => lines.map((line, i) => {line});
const MessageBubble = ({animationClass, column, y, height, fontSize, tone, nibSide, text}) => {
const x = MESSAGE_X[column];
const textX = x + MESSAGE_PADDING_X;
const lineHeight = fontSize * 1.4;
const textBlockHeight = (text.length - 1) * lineHeight + fontSize;
const textY = y + (height - textBlockHeight) / 2 + fontSize - 1;
const nibCenterY = y + height / 2;
const bubbleRight = x + MESSAGE_WIDTH;
const bubbleBottom = y + height;
const bubblePath = nibSide === "left" ? [`M ${x + MESSAGE_RADIUS} ${y}`, `H ${bubbleRight - MESSAGE_RADIUS}`, `Q ${bubbleRight} ${y} ${bubbleRight} ${y + MESSAGE_RADIUS}`, `V ${bubbleBottom - MESSAGE_RADIUS}`, `Q ${bubbleRight} ${bubbleBottom} ${bubbleRight - MESSAGE_RADIUS} ${bubbleBottom}`, `H ${x + MESSAGE_RADIUS}`, `Q ${x} ${bubbleBottom} ${x} ${bubbleBottom - MESSAGE_RADIUS}`, `V ${nibCenterY + NIB_HEIGHT / 2}`, `L ${x - NIB_WIDTH} ${nibCenterY}`, `L ${x} ${nibCenterY - NIB_HEIGHT / 2}`, `V ${y + MESSAGE_RADIUS}`, `Q ${x} ${y} ${x + MESSAGE_RADIUS} ${y}`, "Z"].join(" ") : [`M ${x + MESSAGE_RADIUS} ${y}`, `H ${bubbleRight - MESSAGE_RADIUS}`, `Q ${bubbleRight} ${y} ${bubbleRight} ${y + MESSAGE_RADIUS}`, `V ${nibCenterY - NIB_HEIGHT / 2}`, `L ${bubbleRight + NIB_WIDTH} ${nibCenterY}`, `L ${bubbleRight} ${nibCenterY + NIB_HEIGHT / 2}`, `V ${bubbleBottom - MESSAGE_RADIUS}`, `Q ${bubbleRight} ${bubbleBottom} ${bubbleRight - MESSAGE_RADIUS} ${bubbleBottom}`, `H ${x + MESSAGE_RADIUS}`, `Q ${x} ${bubbleBottom} ${x} ${bubbleBottom - MESSAGE_RADIUS}`, `V ${y + MESSAGE_RADIUS}`, `Q ${x} ${y} ${x + MESSAGE_RADIUS} ${y}`, "Z"].join(" ");
return ;
};
return ;
};
export const ArchitectureDiagram = () => ;
Every Guava call involves two systems working in parallel: Guava's hosted **Dialog System** and your **Expert** — a service you provide that connects to Guava's API and steers the conversation.
## The Dialog System
The Dialog System is Guava's managed service running in the cloud. It handles everything time-sensitive during a call: receiving the caller's audio, transcribing it, synthesizing a response, and streaming it back to the caller.
Because the entire pipeline runs as a fully integrated architecture rather than a chain of off-the-shelf APIs, the Dialog System delivers best-in-class latency and naturalness.
## The Expert
The Expert is the code you write. Using the [Guava SDK](/sdk-reference/agent), it connects to the Dialog System over a persistent WebSocket and steers the agent in real time.
Because your Expert is just code, you can do anything: query a CRM or database, hit an external API, or chain into another specialized AI sub-agent.
The Dialog System always interacts with your Expert asynchronously, so you can spend time on complex tasks and reasoning without the caller ever noticing a pause.
During development, your Expert runs on your local machine, and Guava routes calls to it directly. You can rapidly iterate by changing the code and restarting the process — no public web server or ngrok required.
### Structured Callbacks
As the Dialog System converses with the caller in natural language, it maintains a separate communication channel with your Expert.
This channel consists of callbacks that follow a consistent structure and schema, and are designed to be plugged into backend systems like RAG and intent recognition.
You decide which callbacks your Expert can handle — all are optional, and the Dialog System will adapt appropriately.
```python Python theme={null}
@agent.on_question
def on_question(call: guava.Call, question: str) -> str:
# The agent will invoke this when the caller asks a question that can't be
# answered from the current context. Use our ready-to-use RAG module. Or
# plug in your own custom one.
return document_qa.ask(question)
@agent.on_action_request
def on_action_request(call: guava.Call, request: str) -> list[SuggestedAction]:
# The agent will invoke this callback when the caller requests a new action.
# Use our ready-to-use intent classification system. Or plug in a custom one.
return intent_recognizer.classify(request)
```
```typescript TypeScript theme={null}
agent.onQuestion(async (call: guava.Call, question: string) => {
// The agent will invoke this when the caller asks a question that can't be
// answered from the current context. Use our ready-to-use RAG module. Or
// plug in your own custom one.
return await documentQA.ask(question);
});
agent.onActionRequest(async (call: guava.Call, request: string) => {
// The agent will invoke this callback when the caller requests a new action.
// Use our ready-to-use intent classification system. Or plug in a custom one.
return await intentRecognizer.classify(request);
});
```
If you want ready-to-use implementations of these callbacks, you can use our helper library which contains implementations of RAG, intent recognition, and more.
But all of these are optional modules and we encourage you to build your own domain specific versions.
### Assign Tasks to your Agents
Instead of using a single large prompt for your agent, Guava recommends that you use [Tasks](/sdk-reference/tasks).
A task is a checklist of items that you assign to your agent. These items can include things to say to the caller, as well as information to collect as [Fields](/sdk-reference/field).
You will receive a callback when your Agent has completed your task and is awaiting more instructions.
```python Python theme={null}
@agent.on_call_start
def on_call_start(call: guava.Call):
call.set_task(
"waitlist",
objective="Add callers to the waitlist.",
checklist=[
guava.Field(key="caller_name", field_type="text"),
guava.Field(key="party_size", field_type="integer"),
guava.Field(key="phone_number", field_type="text"),
"Read the phone number back to the caller to confirm.",
],
)
@agent.on_task_complete("waitlist")
def on_waitlist_done(call: guava.Call):
print("Added caller to waitlist:", call.get_field("caller_name"))
# End the call, transfer, or chain into another task.
call.hangup("Thank the caller and let them know we'll text when their table is ready.")
```
```typescript TypeScript theme={null}
agent.onCallStart(async (call) => {
await call.setTask({
taskId: "waitlist",
objective: "Add callers to the waitlist.",
checklist: [
guava.Field({ key: "caller_name", fieldType: "text" }),
guava.Field({ key: "party_size", fieldType: "integer" }),
guava.Field({ key: "phone_number", fieldType: "text" }),
"Read the phone number back to the caller to confirm.",
],
});
});
agent.onTaskComplete("waitlist", async (call) => {
console.log("Added caller to waitlist:", await call.getField("caller_name"));
// End the call, transfer, or chain into another task.
await call.hangup("Thank the caller and let them know we'll text when their table is ready.");
});
```
## Deploying your Expert
When it's time to move to production, you'll want your Expert deployed in a highly-available configuration, ready to handle calls at any time. Because Guava Experts only make outbound connections, it's easy to run an Expert behind a NAT or firewall.
You have two options for deploying your Expert:
* **Your Infrastructure** — deploy to your own servers, VM, or serverless compute platform. You control the environment.
* **Guava Hosting** — push your Expert with a single [`guava deploy`](/cli-reference/cli-reference) command and Guava manages the rest, including horizontal scaling and redundancy.
See the [Deployment guide](/guides/deployment) for a full walkthrough of both options.
## What to read next
* The [Quickstart](/getting-started/quickstart) shows you how to set up your dev environment and create your first agent.
* The [Example Walkthroughs](/getting-started/inbound-rag-example) show full Expert implementations for common scenarios, including Q\&A and scheduling.
* Once you're comfortable with the basics, the [SDK Reference](/sdk-reference/runner) covers every callback and command in detail.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.