# Agent Creation Workflow

## Critical Workflow Order

**IMPORTANT**: `knowledge_base_id` can ONLY be set at agent creation time. The `update_agent` endpoint does NOT support changing it — the backend silently ignores the field. Therefore, always create the KB BEFORE creating the agent.

The correct sequence for creating a fully functional agent:

1. **`fetch_brandkit(identifier=<domain>)`** — Pre-fetch brand data (no agent_id needed yet).
2. **`create_knowledge_base(name=<name>)`** — Create an empty KB, get the `dataset_id` UUID.
3. **`import_knowledge_from_website(dataset_id=<uuid>, url=<site>)`** — Start async content crawl into the KB.
4. **`create_agent(name=..., knowledge_base_id=<uuid>, ...)`** — Create agent WITH the KB attached. This is the ONLY time you can set `knowledge_base_id`.
5. **`fetch_brandkit(identifier=<domain>, agent_id=<new_id>)`** — Re-fetch with agent_id to attach brandkit.
6. **`update_brandkit(...)`** — Customize persona, appearance_config, conversation starters, welcome message.
7. **`update_agent_instruction(agent_id, instructions=...)`** — This creates the **draft runtime config** (required before publishing).
8. **`publish_agent(agent_id)`** — Publishes the draft config to make it live.
9. **Test and verify** — Test only after publishing.

## Critical Gotchas

### Draft Config is Required Before Publishing
`publish_agent` will fail with "No draft configuration found" unless you call `update_agent_instruction` first. Simply calling `create_agent` with instructions does NOT create a draft config — it sets the agent-level instructions but the runtime config system is separate.

### system_rules via update_agent Don't Propagate to Runtime Config
Calling `update_agent(system_rules=...)` sets rules on the agent object, but the published runtime config may show empty `system_rules`. **Workaround**: Embed guardrails directly in the instructions passed to `update_agent_instruction`.

### Brandkit Attachment — Use fetch_brandkit, Not create_brandkit
`fetch_brandkit(identifier=<domain>, agent_id=<id>)` is the reliable one-step method. `create_brandkit` requires precise struct formats (`minimized_button_label` as object, `agent_id` in body) and is error-prone.

### Annotations as Immediate Safety Net
Create annotations for critical guardrail responses BEFORE the knowledge base is ready. Annotations work without a KB and guarantee exact answers for:
- Fee-blocking responses (high priority)
- Competitor comparison deflections
- Unavailable product/service responses
- Campus/location redirect links
- Accreditation/ranking verified data

### appearance_config Structure
The appearance_config has two parallel sections: `widget` (for web widget) and `ai_bar` (for AI bar). Both need the same structure:
```json
{
  "widget": {
    "name": "Agent Name",
    "welcome_message": {"message": "...", "popup_mode": true},
    "conversation_starter": {"messages": ["Q1", "Q2", "Q3"], "popup_mode": true},
    "brand_logo": {"url": "..."},
    "color_theme": {"primary_color": "#hex"},
    "display_form_immediately": false
  },
  "ai_bar": { ... same structure ... }
}
```

## Typical Cost for Full Agent Creation
A complete agent creation workflow (brandkit + create + KB + annotations + publish + test attempts) costs approximately $2.50-3.50 with Claude Sonnet, spanning ~25 iterations.
