Tracing

The @projectkate.trace() decorator records your agent's function calls as spans - capturing inputs, outputs, duration, and any errors. These traces are used for evaluation and knowledge improvement.

Basic Usage

import projectkate

projectkate.init(
    api_url="https://api.projectkate.com",
    api_key="your-api-key",
    agent_name="My Agent",
)

@projectkate.trace("generate_response")
async def generate_response(user_input: str) -> str:
    response = await llm.chat(
        messages=[{"role": "user", "content": user_input}]
    )
    return response.content

Parameters

@projectkate.trace(name=None, *, span_kind="LLM")

Parameter	Type	Default	Description
`name`	`str \| None`	`None`	Span name (defaults to function name)
`span_kind`	`str`	`"LLM"`	Span type identifier

What Gets Recorded

Each traced function call records:

Function name (or custom span name)
Inputs - function arguments (serialized to JSON)
Output - return value (serialized to JSON)
Duration - execution time in milliseconds
Errors - any exceptions raised
Span kind - the type of operation

Sync and Async Functions

The decorator works with both sync and async functions:

# Async function
@projectkate.trace("async_operation")
async def fetch_data(query: str) -> dict:
    return await api.search(query)

# Sync function
@projectkate.trace("sync_operation")
def process_data(data: dict) -> str:
    return transform(data)

Nested Traces

Trace multiple functions to capture the full execution flow:

@projectkate.trace("handle_request")
async def handle_request(user_input: str) -> str:
    context = await research(user_input)
    return await generate(user_input, context)

@projectkate.trace("research")
async def research(query: str) -> str:
    results = await search_tool(query)
    return summarize(results)

@projectkate.trace("generate")
async def generate(input: str, context: str) -> str:
    return await llm.chat(messages=[
        {"role": "system", "content": context},
        {"role": "user", "content": input},
    ])

This produces a trace with three spans showing the full execution hierarchy.

Automatic Redaction

The decorator automatically redacts sensitive values from trace inputs. Keys matching these patterns are replaced with "[REDACTED]":

api_key
password
token
secret
credentials

@projectkate.trace("call_api")
async def call_api(endpoint: str, api_key: str) -> dict:
    # api_key will be recorded as "[REDACTED]" in the trace
    ...

Silent Failure

Tracing never breaks your agent. If recording fails (network issue, serialization error), the function executes normally and the trace is silently dropped.

Next Steps

Runs - group traces into evaluatable runs
Initialization - configure the SDK

Tracing

On this page