Tool maintenance

Update tool code (Python functions), debug errors using logs, manage credentials, and fix integration issues.

Update tool code, debug errors using conv.log, rotate API credentials, and fix integration issues without taking the agent offline.

Quick reference

I need to…	Action
Update tool code	Edit in Function Editor → Save → Test in Agent Chat
Debug a tool error	Analytics > Conversations > Voice → Diagnosis → check logs
Update API credentials	Workspace homepage > Secrets tab → Edit → Save
Add logging	Use conv.log.info() in code
Fix tool not triggering	Review KB action or rules → clarify description
Update API integration	Integrations > API → edit endpoint

Updating tool code

1. Go to Tools and select the tool
2. Edit the Python function in the Function Editor
3. Save, then test in Agent Chat
4. Review logs in Conversation Review → Diagnosis
5. Publish when satisfied

Always test tool changes in Sandbox before promoting to Live.

Example: updating an API endpoint

def book_reservation(date, time, party_size, special_requests=None):
    conv.log.info(f"Booking for {party_size} guests on {date} at {time}")

    response = requests.post(
        "https://api.example.com/v2/bookings",
        json={"date": date, "time": time, "guests": party_size,
              "special_requests": special_requests or ""},
        headers={"Authorization": f"Bearer {conv.utils.get_secret('booking_api_key')}"}
    )

    if response.status_code == 200:
        conv.log.info("Booking successful")
        return {"utterance": "Your reservation is confirmed."}
    else:
        conv.log.error(f"Booking failed: {response.text}")
        return {"utterance": "I'm having trouble completing your reservation. Let me transfer you to someone who can help."}

Debugging

Using conv.log

conv.log.info("Starting payment processing")       # general flow
conv.log.warning("Customer account has low balance") # potential issues
conv.log.error(f"Payment API returned: {error}")     # failures
conv.log.info("Processing order", pii=True)          # sensitive data

Logs appear in Conversation Review → Diagnosis, Agent Chat (during testing), and the Conversations API.

Common debugging steps

1. Review Diagnosis logs for the failing tool
2. Reproduce the issue in Agent Chat
3. Check tool inputs – are parameters being passed correctly?
4. Validate external APIs directly (Postman, curl)
5. Review the tool description – is it clear when the tool should trigger?

Common errors

Error	Likely cause	Fix
Tool not triggering	Unclear description or KB action	Simplify description; clarify when to call it
Wrong parameters	LLM misunderstanding	Improve parameter names and descriptions
Timeout	Slow API or complex logic	Add delay controls; optimize code
Auth failures	Expired credentials	Update secrets
Import errors	Missing library	Check available libraries

Managing secrets

When API keys or credentials change:

1. Go to the Secrets tab on the workspace homepage
2. Find and edit the secret
3. Save, then test all tools using it

api_key = conv.utils.get_secret("my_api_key")
headers = {"Authorization": f"Bearer {api_key}"}

• Rotate credentials every 90 days
• Use descriptive names (stripe_live_api_key, not key1)
• Test all dependent tools after rotation

Managing API integrations

Configure per-environment endpoints in Integrations > API:

• Sandbox – test/staging endpoints
• Pre-release – UAT endpoints
• Live – production endpoints

You won’t call production APIs during testing.

Optimizing performance

If tools are slow:

1. Add delay controls with filler phrases (“Let me check that for you.”)
2. Cache frequently-accessed data
3. Reduce unnecessary API calls
4. Simplify logic and remove unnecessary processing

You can reference state variables in delay responses using $. For example: Still checking availability at $branch_name...

Improving tool triggering

If the agent isn’t calling your tool when expected:

1. Simplify the description – make it clear when to call the tool
2. Update KB actions – ensure topics reference the tool correctly
3. Check for conflicts – ensure other tools aren’t being called instead

Bad description: “Handles reservations”

Good description: “Call this tool when the user wants to book a table. Required: date, time, party_size. Only call after confirming all three with the user.”

Related pages

• Tools overview – tool capabilities
• Secrets – credential management
• conv.log reference – structured logging
• Delay controls – managing latency
• Test sets – automated regression testing to verify tool changes
• Alerts API – automated alerts for tool errors, latency, and API failures