Agent Guidance

Agent Guidance lets you customize how the AI agent reasons and selects actions for your specific product. This is configured in the admin dashboard, not in SDK code.

What is Agent Guidance?

Agent Guidance is custom instructions injected into the AI agent's prompt at runtime. Use it to:

• Prefer certain action types — Tell the agent to prefer API actions over navigation actions
• Define workflows — Describe multi-step processes the agent should follow
• Provide domain knowledge — Help the agent understand your product's terminology and best practices

Configuring Agent Guidance

Example Agent Guidance

Here's an example for a BI tool like Superset:

PREFER API ACTIONS OVER NAVIGATION:
- If both "create_chart" (API action) and "navigate_to_chart_builder" (navigation) are available, prefer the API action
- API actions execute instantly; navigation requires user to complete forms manually
- Only use navigation actions when no API action exists for that task

DASHBOARD CREATION WORKFLOW:
When user wants to build a dashboard with multiple charts:
1. First use list_datasets to find available data sources
2. Then use get_dataset_columns to understand the schema
3. Based on column types, choose appropriate chart types:
   - Categorical/text columns → bar charts, pie charts
   - Numeric columns → big number totals, aggregations
   - Date/time columns → time series, trend charts
4. Create a plan with this pattern:
   - create_new_dashboard (with title)
   - create_chart (chart 1)
   - add_chart_to_dashboard
   - create_chart (chart 2)
   - add_chart_to_dashboard
   - ... repeat for each chart
   - navigate_to_dashboard (view the result)

Writing Effective Guidance

Be Specific

Tell the agent exactly what to prefer and when:

// Good - specific conditions
When creating charts, always check get_dataset_columns first to understand the schema.

// Less helpful - too vague
Be careful with charts.

Reference Your Actions

Use exact action names from your action definitions:

// Good - references actual action names
Use create_chart_api instead of navigate_to_chart_builder when available.

// Less helpful - generic terms
Use the API when possible.

Describe Multi-Step Workflows

Help the agent chain actions together:

// Good - clear workflow
For dashboard creation:
1. list_datasets → find data
2. get_dataset_columns → understand schema
3. create_dashboard → create container
4. create_chart → add visualizations
5. navigate_to_dashboard → show result

// Less helpful - no sequence
Use create_dashboard and create_chart actions.

Keep It Focused

Only include guidance relevant to common user requests. Too much guidance can confuse the agent.

How It Works

When a user sends a message:

1. Agent receives context — Your agent guidance is injected into the agent's prompt
2. Agent reasons — The agent uses your guidance to decide which actions to search for
3. Actions are matched — The agent finds relevant actions from your defined actions
4. Plan is created — For multi-step tasks, the agent creates a plan following your workflows

Relationship to Actions

Agent Guidance works alongside your action definitions:

Best Practices

1. Start simple — Add guidance only when you notice the agent making suboptimal choices
2. Be descriptive — The agent interprets natural language, so be clear and explicit
3. Test iteratively — Try different phrasings and observe the agent's behavior
4. Update as needed — Unlike code, agent guidance can be changed without redeployment