Tools and Events

Track when your agent uses tools during test conversations. This helps you test your agent’s tool usage patterns and use them in test assertions.

You can also track internal-event and public-event.

Public events can be a form or widget that appears in the chat and is visible to the end user. It is important to distinguish between internal and public events because assertions treat them differently. Private events are everything else that you would like to track and test assertions against. It could be knowledge articles, data that has been collected during the conversation and more.

What Are Tool Calls?

Tool calls represent actions your agent takes during a conversation, like searching a database, calling an API, or retrieving documents. If you register tool calls, assertions can judge if they were called correctly and in the expected order.

Registering a Tool Call or Event

# After your agent makes a tool call
response = requests.post(
    f"{base_url}/test-results/{test_result_id}/conversation",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "type": "tool",
        "name": "search_knowledge_base",
        "metadata": {
            "query": "API authentication",
            "results_count": 5,
            "execution_time_ms": 234
        }
    }
)

Request Fields

• type (required): Must be "tool" for tool calls, for events "internal-event" or "public-event"
• name (required): Identifier for the tool (e.g., "search_database", "call_api")
• metadata (optional): Any JSON data up to 10KB—tool arguments, results, timing data, etc.

When to Register

Register tool calls after your agent executes them but before sending the next message to Voxli:

# 1. Get message from Voxli
voxli_message = response.json()["message"]

# 2. Send to your agent
agent_response = your_agent.process(voxli_message)

# 3. Record any tool calls your agent made
requests.post(
    f"https://api.voxli.io/test-results/{test_result_id}/conversation",
    json={"type": "tool", "name": "cancel-order", "metadata": {...}}
)

# 4. Record your agent's response
requests.post(
    f"https://api.voxli.io/test-results/{test_result_id}/conversation",
    json={"type": "message", "content": agent_response.text}
)

# 5. Get next message from Voxli