# Instruction Optimization Workflow

## Analysis Phase

1. **Get current config** — `get_agent` + `get_runtime_config(status=active)` to see what's live.
2. **Review conversations** — `get_analytics` first for overview, then `list_conversations` to find problematic ones. Read actual messages with `get_conversation_messages`.
3. **Check knowledge gaps** — `retrieve_knowledge` with common user queries to see what the agent retrieves. If results are poor, the KB needs enrichment.

## Improvement Phase

1. **Instructions should be structured** — Use markdown headers: Role & Identity, Core Flow, Guardrails, Communication Style.
2. **Embed guardrails directly in instructions** — `system_rules` set via `update_agent` may NOT propagate to the published runtime config. Always include critical guardrails (NEVER/ALWAYS rules) directly in the instruction text passed to `update_agent_instruction`.
3. **Use annotations for FAQ overrides** — `create_annotation` with exact Q&A pairs takes priority over KB retrieval. Use for critical questions that must have exact answers. Annotations work even without a KB attached.
4. **Keep instructions under 4000 tokens** — Very long instructions degrade LLM performance. Be concise and use bullet points.

## Publishing Flow

The correct publishing flow is:
1. `update_agent_instruction(agent_id, instructions=...)` — creates/updates the **draft runtime config**
2. `publish_agent(agent_id)` — publishes the draft to make it live
3. Verify: `get_runtime_config(agent_id, status=active)` — confirm instructions are correct

**Critical**: `publish_agent` requires a draft config. If you only used `create_agent` or `update_agent`, there is no draft config — you MUST call `update_agent_instruction` first.

## Testing Phase

1. **Publish before testing** — `send_test_message` (chat-preview) requires a published runtime config. An unpublished agent returns 400 errors.
2. **chat-preview endpoint may return 400** — This is a known backend issue. If test messages fail, verify the agent is published and has an active runtime config (`get_runtime_config(status=active)`).
3. **For systematic testing** — Use the testing pipeline: `create_test_suite` → `add_test_case` (multiple) → `create_test_run` → `get_test_run` → `create_run_analysis`.
4. **Use `generate_instruction`** — After analyzing test failures with `analyze_failures`, use `generate_instruction` to get AI-suggested improvements.

## Annotation Patterns for Guardrails

Annotations are the most reliable way to enforce guardrail responses. Create them for:

| Guardrail | Example Questions | Fixed Response |
|-----------|------------------|----------------|
| Fee blocking | "What's the fee?", "How much does it cost?" | "For fee information, please contact..." |
| Competitor deflection | "Is X better than Y?", "X vs Y" | "I can help with information about [brand]..." |
| Unavailable items | "Do you offer [thing]?" | "Sorry, [thing] is not available." |
| Location redirects | "Tell me about [other branch]" | "For [branch], please visit: [URL]" |
| Verified facts | "What's [brand]'s ranking?" | Exact verified answer with source links |

## Common Instruction Patterns

- **Lead capture agent**: Step-by-step flow (greet → collect name → phone → email → interest → answer → qualify). Collect one field at a time. If user asks a question first, answer it, then return to collection.
- **Support agent**: Prioritize KB retrieval, with clear escalation rules and human handoff triggers.
- **Sales agent**: Include objection handling, CTA patterns, and qualification criteria.
- **Multi-location agent**: Define primary location, redirect rules for other locations with specific URLs.
