Guide: Use Marketplace Tools

This guide walks you through using marketplace tools in your agent - from discovery to execution to error handling.

Prerequisites

Kate account with an API key
An agent registered on Kate
pip install projectkate
An LLM client (openai or anthropic package)

How Tools Appear

You don't browse a catalog to find tools. Kate's discovery process identifies capability gaps in your agent and finds matching tools automatically. When a tool is discovered:

It appears in your agent's tool management page in the dashboard
If you're in auto approval mode and credentials are configured, it's enabled immediately
If you're in manual mode, you review and enable it

Step 1: Set Approval Mode

In the dashboard, go to your agent's settings and choose an approval mode:

Auto - new tools are enabled automatically once credentials are provided
Manual - you review each tool before enabling it

For getting started, manual mode gives you more control.

Step 2: Provide Credentials

Some tools need API keys or other credentials to work. The dashboard shows which tools need credentials and what keys are required.

You can set credentials in the dashboard or via the API:

import asyncio
from projectkate import KateClient

async def setup_credentials():
    async with KateClient(api_key="your-api-key") as client:
        # Set a single credential
        resp = await client._request(
            "POST",
            f"/agents/{agent_id}/env-vars",
            json={"key": "WEATHER_API_KEY", "value": "your-weather-key"},
        )

        # Or bulk set multiple credentials
        resp = await client._request(
            "POST",
            f"/agents/{agent_id}/env-vars/bulk",
            json={
                "vars": [
                    {"key": "WEATHER_API_KEY", "value": "your-weather-key"},
                    {"key": "SEO_API_KEY", "value": "your-seo-key"},
                ]
            },
        )

asyncio.run(setup_credentials())

Credentials are encrypted at rest and scoped per-tool - each tool only sees the secrets declared in its manifest.

Step 3: Use `tool_loop()` in Your Agent

The simplest way to use marketplace tools is tool_loop(). It handles everything: discovering available tools, sending them to your LLM, executing tool calls, and feeding results back.

With OpenAI

import asyncio
from openai import AsyncOpenAI
import projectkate

projectkate.init(
    api_url="https://api.projectkate.com",
    api_key="your-kate-api-key",
    agent_name="Content Marketing Strategist",
)

async def main():
    client = AsyncOpenAI()

    result = await projectkate.tool_loop(
        client,
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "You are a content marketing strategist."},
            {"role": "user", "content": "What's the weather in San Francisco? I need it for a local event post."},
        ],
    )

    print(result.content)
    print(f"Tool calls made: {result.tool_calls_made}")
    print(f"LLM rounds: {result.rounds}")

asyncio.run(main())

With Anthropic

import asyncio
from anthropic import AsyncAnthropic
import projectkate

projectkate.init(
    api_url="https://api.projectkate.com",
    api_key="your-kate-api-key",
    agent_name="Content Marketing Strategist",
)

async def main():
    client = AsyncAnthropic()

    result = await projectkate.tool_loop(
        client,
        model="claude-sonnet-4-20250514",
        messages=[
            {"role": "user", "content": "Analyze the top keywords for example.com in the US market."},
        ],
    )

    print(result.content)

asyncio.run(main())

tool_loop() auto-discovers your agent's available tools. The LLM decides when and how to call them based on the conversation.

Step 4: Add Local Tools

You can mix marketplace tools with your own local functions using LocalTool:

from projectkate import LocalTool

def format_report(data: dict, format: str = "markdown") -> str:
    """Format analysis data into a readable report."""
    if format == "markdown":
        lines = [f"# {data.get('title', 'Report')}"]
        for key, value in data.items():
            if key != "title":
                lines.append(f"- **{key}**: {value}")
        return "\n".join(lines)
    return str(data)

result = await projectkate.tool_loop(
    client,
    model="gpt-4o",
    messages=messages,
    local_tools=[
        LocalTool(
            name="format_report",
            description="Format analysis data into a readable report",
            parameters={
                "type": "object",
                "properties": {
                    "data": {"type": "object", "description": "The data to format"},
                    "format": {"type": "string", "enum": ["markdown", "plain"]},
                },
                "required": ["data"],
            },
            fn=format_report,
        ),
    ],
)

Local tools run in your process. Marketplace tools run in Kate's isolated environment. The LLM sees both and can use either.

Step 5: Handle Errors

Three tool-specific errors can occur:

from projectkate import (
    KateCredentialError,
    KateBalanceError,
    KateToolError,
)

try:
    result = await projectkate.tool_loop(
        client,
        model="gpt-4o",
        messages=messages,
    )
except KateCredentialError:
    # Tool needs credentials you haven't provided yet
    # Check the dashboard for which keys are missing
    print("Missing credentials  -  check your agent's tool management page")

except KateBalanceError:
    # Not enough tokens to execute the tool
    print("Insufficient balance  -  add tokens to your wallet")

except KateToolError:
    # The tool itself failed during execution
    print("Tool execution failed  -  the seller's tool encountered an error")

Inside tool_loop(), errors are caught and returned to the LLM as error messages so it can adjust. The exceptions above are raised only for unrecoverable failures.

Step 6: Use Lower-Level APIs

If you need more control than tool_loop() provides, use the individual functions:

import projectkate

# Discover available tools (OpenAI function-calling format)
tools = await projectkate.get_tools(format="openai")

# Execute a specific tool
result = await projectkate.call_tool(
    "get_weather",
    {"city": "San Francisco", "units": "metric"},
)
print(result.output)       # {"city": "San Francisco", "temperature": 18, ...}
print(result.tokens_charged)  # 5

Or use the management client for admin operations:

async with KateClient(api_key="your-api-key") as client:
    # List tools for an agent
    tools = await client.tools.list(agent_id="your-agent-id")

    # Check credential status
    statuses = await client.tools.status(agent_id="your-agent-id")
    for s in statuses:
        print(f"{s.tool_name}: {s.status} (missing: {s.missing_keys})")

Next Steps

Tools SDK Reference - full tool_loop() API reference
Tools API Reference - REST API endpoints
Environment Variables API - credential management
Tools Overview - how the tool marketplace works

Guide: Use Marketplace Tools

On this page