> ## Documentation Index
> Fetch the complete documentation index at: https://docs.valiqor.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agno

> Auto-instrument Agno agents with tracing for agent runs, tool calls, and MCP tool integration.

Valiqor automatically traces Agno `Agent.arun()` calls, capturing the full
agent lifecycle including model interactions, tool executions, and MCP
tool schemas.

<Info>
  Agno tracing requires the `agno` package to be installed separately.
  There is no `valiqor[agno]` extra — install `agno` directly alongside
  `valiqor`.
</Info>

***

## Install

```bash theme={"system"}
pip install valiqor agno
```

***

## Zero-Config (Recommended)

Add a single import at the top of your app — all Agno agent runs are
automatically traced:

```python theme={"system"}
import valiqor.auto  # ← Add this line

from agno.agent import Agent
from agno.models.openai import OpenAIChat

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    description="You are a helpful research assistant",
    instructions=["Be concise", "Cite sources"]
)

# Async agent run — automatically traced
import asyncio
response = asyncio.run(agent.arun("What are the latest AI trends?"))
print(response.content)
```

***

## Selective Instrumentation

If you only want Agno tracing:

```python theme={"system"}
from valiqor.trace import agno_autolog

agno_autolog()
```

***

## Tool Call Tracing

When your Agno agent uses tools, each tool execution is captured as a
child span with full details:

```python theme={"system"}
import valiqor.auto
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.duckduckgo import DuckDuckGoTools

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[DuckDuckGoTools()],
    description="You are a research assistant with web search"
)

import asyncio
response = asyncio.run(agent.arun("Search for recent news about AI safety"))
```

Each tool call span captures:

| Field               | Description                 |
| ------------------- | --------------------------- |
| `tool_name`         | Name of the tool            |
| `call_id`           | Unique tool call identifier |
| `arguments`         | Raw and parsed arguments    |
| `result`            | Tool output content         |
| `error`             | Error info (if failed)      |
| `description`       | Tool description            |
| `execution_metrics` | Performance data            |

***

## MCP Tool Support

Agno's MCP (Model Context Protocol) tool integration is automatically
detected. When your agent uses MCP tools, Valiqor captures the MCP
server metadata and tool schemas:

```python theme={"system"}
import valiqor.auto
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.mcp import MCPTools

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[MCPTools(server_name="my-server", transport="sse", url="http://localhost:8080")]
)
```

MCP-specific data captured includes server name, transport type, URL,
and tool parameter schemas.

***

## What Gets Captured

Each traced Agno agent call records:

| Field               | Description                               |
| ------------------- | ----------------------------------------- |
| `model`             | Model name from agent instance            |
| `message`           | User input message                        |
| `response`          | Agent response content                    |
| `prompt_tokens`     | Input token count                         |
| `completion_tokens` | Output token count                        |
| `total_tokens`      | Combined token count                      |
| `cost`              | Estimated cost in USD                     |
| `tool_calls`        | Full tool call details (see above)        |
| `mcp_tools`         | MCP server info and tool schemas (if any) |
| `duration_ms`       | Total agent run latency                   |
| `status`            | Success or error                          |

***

## With Workflows

Group multiple agent interactions into a single trace:

```python theme={"system"}
import valiqor.auto
from valiqor.trace import trace_workflow
from agno.agent import Agent
from agno.models.openai import OpenAIChat

researcher = Agent(model=OpenAIChat(id="gpt-4o"), description="Research agent")
writer = Agent(model=OpenAIChat(id="gpt-4o"), description="Writing agent")

async def main():
    with trace_workflow("research-and-write"):
        # Step 1: Research
        research = await researcher.arun("Find key facts about quantum computing")

        # Step 2: Write article
        article = await writer.arun(f"Write an article based on: {research.content}")

import asyncio
asyncio.run(main())
```

Both agent calls appear as child spans under the `research-and-write` trace.

***

## Disabling

```python theme={"system"}
from valiqor.trace import disable_autolog

disable_autolog("agno")    # Disable Agno only
disable_autolog()          # Disable all providers
```

***

## Limitations

* **Async only** — only `Agent.arun()` (async) is traced. Synchronous
  `Agent.run()` is not instrumented. Use `asyncio.run()` for sync
  entry points.
* **Streaming** is not instrumented.
* **Team orchestration** — multi-agent team runs are traced at the
  individual agent level, not at the team coordination level.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Tracing Guide" icon="route" href="/workflows/tracing">
    Learn about traces, spans, workflows, and exporters.
  </Card>

  <Card title="Failure Analysis" icon="magnifying-glass" href="/workflows/failure-analysis">
    Run failure analysis on your traced agent calls.
  </Card>
</CardGroup>