Agent Guidance

Agent Guidance lets you customize how the AI agent reasons and selects tools for your specific product.

What is Agent Guidance?

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

• Prefer certain tool types — Tell the agent to prefer API tools over navigation tools
• 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

There are two ways to configure agent guidance:

Option 1: Admin Dashboard (no deploy required)

Option 2: Code Sync (version-controlled with your tools)

Place an AGENT_GUIDANCE.md file in the directory you pass to --scan. The pillar-sync CLI picks it up automatically alongside your tool definitions -- no barrel file or JS export needed.

<!-- src/tools/AGENT_GUIDANCE.md -->
PREFER API TOOLS OVER NAVIGATION:
- When both an API tool and a navigation tool can accomplish a task, prefer the API tool
- API tools execute instantly; navigation requires the user to complete forms manually

ORDER PROCESSING:
When a user asks to process an order:
1. Look up the order details first
2. Verify inventory is available
3. Generate the shipment
4. Notify the customer when complete

Then sync during CI/CD:

PILLAR_SLUG=your-product PILLAR_SECRET=xxx npx pillar-sync --scan ./src/tools

The scanner reads AGENT_GUIDANCE.md from the root of the scan directory and includes it in the manifest. This keeps your guidance in version control alongside the tool files it references.

Example Agent Guidance

PREFER API TOOLS OVER NAVIGATION:
- When both an API tool and a navigation tool can accomplish a task, prefer the API tool
- API tools execute instantly; navigation requires the user to complete forms manually
- Only use navigation tools when no API tool exists for that task

GENERATING REPORTS:
When a user asks for a report:
1. First discover what data sources are available
2. Inspect the schema to understand which fields and metrics exist
3. Build the report with appropriate filters
4. Export it if the user wants a downloadable file

PROCESSING REFUNDS:
When a user asks to process a refund:
1. Look up the order first to verify it exists and check its status
2. Only proceed with the refund if the order is eligible
3. Notify the customer after the refund is processed

Writing Effective Guidance

Describe Capabilities, Not Tool Names

Write guidance that describes what the copilot can do and how it should approach tasks. The agent will search for the right tools to fulfill each step.

// Good - describes the approach
When a user asks to process a refund, look up the order first to verify its status
before proceeding.

// Less helpful - too coupled to implementation
When processing refunds, always call get_order first then call process_refund.

Tool names change as you iterate. Guidance that describes behavior stays correct even when you rename or restructure your tools.

Be Specific About Approach

Tell the agent what to prefer and the order of operations:

// Good - specific about the approach
When building visualizations, always test the query against the data source first.
If the test returns no data, adjust and retry. Only create the visualization after
the query is confirmed working.

// Less helpful - too vague
Be careful when creating charts.

Describe Multi-Step Workflows

Help the agent understand the sequence of steps for complex tasks:

// Good - clear workflow describing what to do at each step
For user onboarding:
1. Set up a new workspace for the user
2. Invite their team members
3. Connect any integrations they need
4. Show them the dashboard when everything is ready

// Less helpful - just lists actions with no context
Use create_workspace and invite_users tools.

Keep It Focused

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

Verification Workflows

For copilots that create resources via API (charts, dashboards, reports), write guidance that tells the agent to validate before committing. This prevents the agent from creating broken configurations it can't detect afterward.

Describe what the agent should do at each step, not which specific tool to call:

CREATING VISUALIZATIONS:
When building charts or dashboards:
1. First discover what data sources are available
2. Inspect the schema to understand column names and types
3. Test the query to confirm it returns data before creating anything
4. If the test returns no data or errors, adjust the query and re-test
5. Only create the visualization after the query is validated
6. Navigate to the result so the user can see it

PREFER API OVER NAVIGATION:
- Creating resources via API is instant and returns structured confirmation
- Navigation requires the user to fill out forms manually
- Only navigate when there is no API-based alternative

This describes the workflow the agent should follow without coupling to specific tool names. The agent will search for the right tools to fulfill each step.

This works together with per-tool guidance fields. The AGENT_GUIDANCE.md defines the overall workflow, while each tool's guidance field provides specific instructions for that tool (required fields, common pitfalls, return values).

<!-- AGENT_GUIDANCE.md -->
CREATING VISUALIZATIONS:
When building charts or dashboards:
1. Discover available data sources
2. Inspect the data to understand what columns and metrics exist
3. Test the query before creating -- if it fails, fix and retry
4. Create the visualization only after validation succeeds
5. Show the user the result

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 tools to search for
3. Tools are matched — The agent finds relevant tools from your defined tools
4. Response is generated — The agent responds with suggested tools following your workflows

Relationship to Tools

Agent Guidance works alongside your tool 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. Keep tools focused — Smaller tools with tight schemas work better than large, multi-mode tools