Skip to main content

Tracing and monitoring

Every agent run returns a trace of the steps it took, the tools it called, the credits it used and how long it ran.

Tracing is on by default. Read it from the run result, with no extra setup, or monitor every run in the aixplain app dashboard.

Try it​

from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

web_search = aix.Tool.get("tavily/tavily-web-search/tavily")
web_search.allowed_actions = ["search"]

agent = aix.Agent(
    name="Traced research agent",
    description="Researches topics on the web.",
    instructions="Use web search for anything time-sensitive. Answer in two sentences.",
    tools=[web_search],
).save()

result = agent.run("What are the most popular programming languages this year?")

print("Status: ", result.status)
print("Steps:  ", [step["unit"]["name"] for step in result.data.steps])
print("Credits:", result.used_credits)
print("Time:   ", round(result.run_time, 1), "s")
Show output

Inspecting steps​

result.data.steps is a list with one entry per model or tool call. Each step names the agent that ran it (agent) and the model or tool it called (unit).

for number, step in enumerate(result.data.steps, start=1):
    print(f"{number}. {step['agent']['name']} -> {step['unit']['name']} ({step['unit']['type']})")
    print("   input: ", str(step["input"])[:80])
    print("   output:", str(step["output"])[:80])
    print("   credits:", step["used_credits"], "| time:", step["run_time"], "| status:", step["status"])
Show output
FieldDescription
agentThe agent that ran the step, as a dict with id and name. In a team, this is the subagent or inspector.
unitThe model or tool called, as a dict with id, name and type (model or tool).
input, outputWhat the unit received and returned.
thoughtThe agent's reasoning before the step, when the LLM provides it.
statusStep outcome.
used_credits, api_callsCost and number of API calls for the step.
input_tokens, output_tokens, total_tokensToken counts for model steps.
start_time, end_time, run_timeStep timing.
actionFor inspector steps, the action taken: continue, rerun, edit or abort.
diagnostic_error_codesError codes when the step failed.

Execution metrics​

result.data.execution_stats sums up the run.

stats = result.data.execution_stats
print("API calls:", stats["api_calls"])
print("Credits:  ", stats["credits"])
print("Runtime:  ", round(stats["runtime"], 1), "s")
print("Session:  ", stats["session_id"])
print("Request:  ", stats["request_id"])
Show output

Keep request_id when you contact support about a run.

Trace subagents​

An agent with subagents returns one trace that covers every subagent. The agent field on each step tells you which subagent did the work.

researcher = aix.Agent(
    name="Trace researcher",
    description="Finds facts on the web.",
    instructions="Search the web and return the key facts.",
    tools=[web_search],
)
writer = aix.Agent(
    name="Trace writer",
    description="Writes short, clear summaries from research notes.",
    instructions="Write a three-sentence summary of the notes you receive.",
)
team = aix.Agent(
    name="Traced research team",
    description="Researches a topic, then writes a summary.",
    instructions="Always have the researcher gather facts first, then the writer summarize them.",
    agents=[researcher, writer],
).save(save_subcomponents=True)

result = team.run("Give me a short summary of how the Eiffel Tower was built.")
for step in result.data.steps:
    print(step["agent"]["name"], "->", step["unit"]["name"])
Show output

Watch a run live​

Pass progress_format to print each step while the run happens. Use "status" for one line, or "logs" for a timeline.

result = agent.run("What is the latest stable Python release?", progress_format="logs")
Show output

progress_verbosity=2 adds the agent's thoughts, and 3 adds full inputs and outputs.

Monitor in the dashboard​

Every run also appears in the aixplain app dashboard, with its steps, cost and status. Use it to watch usage and cost across your agents and to open the trace of any run.

Next steps​