Background Execution Metrics

Demonstrates that metrics are fully tracked for background runs.

background_execution_metrics.py
"""
Background Execution Metrics
=============================

Demonstrates that metrics are fully tracked for background runs.

When an agent runs in the background, the run completes asynchronously
and is stored in the database. Once complete, the run output includes
the same metrics as a synchronous run: token counts, model details,
duration, and time-to-first-token.
"""

import asyncio

from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIChat
from agno.run.base import RunStatus
from agno.tools.yfinance import YFinanceTools
from rich.pretty import pprint

# ---------------------------------------------------------------------------
# Config
# ---------------------------------------------------------------------------
db = PostgresDb(
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
    session_table="bg_metrics_sessions",
)

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------
agent = Agent(
    name="BackgroundMetricsAgent",
    model=OpenAIChat(id="gpt-5.6-luna"),
    tools=[YFinanceTools(enable_stock_price=True)],
    db=db,
)


# ---------------------------------------------------------------------------
# Run in background and inspect metrics
# ---------------------------------------------------------------------------
async def main():
    # Start a background run
    run_output = await agent.arun(
        "What is the stock price of AAPL?",
        background=True,
    )

    print(f"Run ID: {run_output.run_id}")
    print(f"Status: {run_output.status}")

    # Poll for completion
    result = None
    for i in range(30):
        await asyncio.sleep(1)
        result = await agent.aget_run_output(
            run_id=run_output.run_id,
            session_id=run_output.session_id,
        )
        if result and result.status in (RunStatus.completed, RunStatus.error):
            print(f"Completed after {i + 1}s")
            break

    if result is None or result.status != RunStatus.completed:
        print("Run did not complete in time")
        return

    # ----- Run metrics -----
    print("\n" + "=" * 50)
    print("RUN METRICS")
    print("=" * 50)
    pprint(result.metrics)

    # ----- Model details breakdown -----
    print("\n" + "=" * 50)
    print("MODEL DETAILS")
    print("=" * 50)
    if result.metrics and result.metrics.details:
        for model_type, model_metrics_list in result.metrics.details.items():
            print(f"\n{model_type}:")
            for model_metric in model_metrics_list:
                pprint(model_metric)

    # ----- Session metrics -----
    print("\n" + "=" * 50)
    print("SESSION METRICS")
    print("=" * 50)
    session_metrics = agent.get_session_metrics()
    if session_metrics:
        pprint(session_metrics)


if __name__ == "__main__":
    asyncio.run(main())

Background task lifetime

background=True detaches the run from its consumer while the event loop remains alive. These standalone scripts use asyncio.run: when the main coroutine exits, unfinished tasks are cancelled, including after a polling timeout. Keep the loop alive until the desired terminal state, or explicitly cancel and observe the run before leaving. A saved pending row alone does not restart execution.

A running AgentOS server can keep work alive after client disconnects. For recovery across process restarts, configure its durable queue.

For this nonstreaming provider call, time_to_first_token is set when the first complete provider response arrives. It does not measure arrival of a streamed first token.

The source's final message conflates a recorded error with a polling timeout. Replace its if result is None or result.status != RunStatus.completed block with the following before inspecting metrics:

    if result is not None and result.status in (RunStatus.error, RunStatus.cancelled):
        print(f"Run ended with {result.status}: {result.content}")
        return
    if result is None or result.status != RunStatus.completed:
        print("Polling timed out; leaving the event loop cancels unfinished work")
        return

In the polling loop, include RunStatus.cancelled alongside completed/error and replace Completed after ... with a status-specific message such as print(f"Run ended with {result.status}").

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U agno "psycopg[binary]" openai sqlalchemy yfinance

Export your OpenAI API key

export OPENAI_API_KEY="your_openai_api_key_here"

Run PgVector

docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql \
  -v pgvolume:/var/lib/postgresql \
  -p 5532:5432 \
  --name pgvector \
  agnohq/pgvector:18

Run the example

Save the code above as background_execution_metrics.py, then run:

python background_execution_metrics.py

Full source: cookbook/02_agents/14_advanced/background_execution_metrics.py