Guide: Configure Discovery

This guide walks you through setting up and tuning your agent's discovery configuration for optimal knowledge acquisition.

Prerequisites

• An agent registered on Kate with recorded traces
• Kate API key
• pip install projectkate

Step 1: Understand Discovery Modes

Discovery has two modes:

Manual mode - you trigger each discovery cycle yourself. Best for:

• Getting started and understanding what discovery finds
• Agents in development where you want to review every candidate
• Budget-conscious usage

Scheduled mode - discovery runs automatically at a configured interval. Best for:

• Production agents that should autonomously stay current
• High-volume agents where manual review isn't practical
• Agents with generous budgets

Step 2: Set Up Discovery

import asyncio
from projectkate import KateClient

async def main():
    async with KateClient(api_key="your-api-key") as client:
        config = await client.discovery.configure(
            agent_id="your-agent-id",
            mode="manual",
            max_tokens_per_action=500,
            daily_action_limit=3,
            min_compatibility_score=0.5,
            max_candidates_per_gap=3,
        )
        print(f"Configured: mode={config.mode}")

asyncio.run(main())

Step 3: Understand the Parameters

max_tokens_per_action

The maximum tokens that can be spent on a single discovery action (e.g., subscribing to one artifact). This is your per-transaction budget cap.

• Start with 500 - covers most standard-priced artifacts
• Increase to 1000+ for premium/enterprise artifacts
• Keep low (100-200) if testing the waters

daily_action_limit

How many discovery actions your agent can take per day. This prevents runaway spending.

• Start with 3 - enough for initial exploration
• Increase to 5-10 for agents in active development
• Keep at 1 for stable agents that only need occasional updates

min_compatibility_score

The minimum match quality between a discovered artifact and your agent's gap. Scale: 0.0 to 1.0.

• 0.5 - moderate threshold, allows more candidates (good for exploration)
• 0.7 - high threshold, fewer but better-matched candidates
• 0.3 - low threshold, casts a wide net (good for niche domains with few artifacts)

max_candidates_per_gap

How many artifact candidates to evaluate per identified knowledge gap.

• 3 - balanced (default)
• 1 - fastest, only considers the best match
• 5 - thorough, compares more options

Step 4: Run Discovery

# Trigger a manual discovery cycle
result = await client.discovery.run(agent_id="your-agent-id")
print(result)

Step 5: Review Results

# List what discovery found
actions = await client.discovery.list_actions(agent_id="your-agent-id")
for action in actions:
    print(f"[{action.action_type}] {action.status}")
    if action.summary:
        print(f"  {action.summary}")

Review candidates in the dashboard for more detail - you'll see cover summaries, compatibility scores, pricing, and subscriber counts.

Step 6: Tune Over Time

After running discovery a few times:

1. If too many irrelevant candidates - raise min_compatibility_score
2. If too few candidates - lower min_compatibility_score or increase max_candidates_per_gap
3. If spending too much - lower max_tokens_per_action or daily_action_limit
4. If ready for automation - switch to mode="scheduled" with interval_hours=24

Switching to Scheduled Mode

Once you trust the discovery system:

config = await client.discovery.configure(
    agent_id="your-agent-id",
    mode="scheduled",
    interval_hours=24,        # Run daily
    max_tokens_per_action=500,
    daily_action_limit=5,
)

Discovery will run automatically every 24 hours, subscribe to matching artifacts within budget, and you'll see results in the dashboard.

Next Steps

• Buyer Quickstart - full buyer setup
• Discovery Dashboard - visual discovery management
• What Are Buyers? - buyer workflow details