Guide: Manual Knowledge Queries

This guide shows how to query knowledge artifacts directly from your code - outside of the automated discovery flow.

When to Use Manual Queries

Testing - verify that a subscribed artifact returns useful answers before integrating into your agent
Exploration - explore what an artifact knows before building automated integration
One-off lookups - your agent needs a specific answer for a specific situation

Prerequisites

An active subscription to at least one artifact
Kate API key
pip install projectkate

Step 1: Find Your Subscriptions

import asyncio
from projectkate import KateClient

async def main():
    async with KateClient(api_key="your-api-key") as client:
        # List your agents
        agents = await client.agents.list()
        for agent in agents:
            print(f"{agent.name} ({agent.id})")

asyncio.run(main())

Check the dashboard to see which artifacts your agents are subscribed to.

Step 2: Query the Artifact

async def query():
    async with KateClient(api_key="your-api-key") as client:
        response = await client.query.ask(
            artifact_id="artifact-id",
            agent_id="your-agent-id",
            question="What's the optimal pricing strategy for a new B2B SaaS product with 3 competitors?",
        )
        print(f"Answer: {response.answer}")
        print(f"Confidence: {response.confidence}")
        print(f"Related topics: {response.related_topics}")
        print(f"Tokens charged: {response.tokens_charged}")

asyncio.run(query())

Step 3: Integrate into Your Agent

Once you've verified the artifact returns useful answers, integrate it into your agent's workflow:

@projectkate.trace("handle_pricing_question")
async def handle_pricing_question(user_input: str) -> str:
    # Query the artifact for domain expertise
    knowledge = await client.query.ask(
        artifact_id="pricing-artifact-id",
        agent_id=agent.id,
        question=user_input,
    )

    # Use the knowledge to enhance your agent's response
    enhanced_response = await llm.chat(messages=[
        {"role": "system", "content": f"Use this expert knowledge to inform your answer: {knowledge.answer}"},
        {"role": "user", "content": user_input},
    ])

    return enhanced_response.content

Tips for Better Queries

Be specific - include context in your question for more targeted answers
Check confidence - if confidence is low, the question may be outside the artifact's domain
Use related_topics - they suggest follow-up questions the artifact can answer well
Monitor token usage - each query costs per_query_tokens, track your spending

Next Steps

Artifact Queries - dashboard query management
Query API - API reference
Adoption Patterns - integration patterns