What this is

tinyagent is a small, dependency-light Python implementation of the HuggingFace Tiny Agents loop, built on any-llm. It gives you:

• A simple agent loop you can read in one sitting.
• Native MCP tool support (stdio, SSE, streamable HTTP).
• OpenTelemetry-based tracing of LLM calls and tool executions, including token counts and cost.
• A callback system for guardrails, metrics, and intentional cancellation.
• Optional A2A and MCP serving so your agent can run as a service.

This package was extracted from any-agent, which still uses tinyagent under the hood as one of its supported framework backends.

Install

pip install mozilla-ai-tinyagent

The PyPI distribution name is mozilla-ai-tinyagent; the import name is tinyagent.

Optional extras:

pip install 'mozilla-ai-tinyagent[a2a]'       # A2A serving
pip install 'mozilla-ai-tinyagent[composio]'  # Composio tools
pip install 'mozilla-ai-tinyagent[all]'       # everything

Quickstart

from tinyagent import TinyAgent, AgentConfig
from tinyagent.tools import search_web, visit_webpage

agent = TinyAgent.create(
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        instructions="Use the tools to find an answer.",
        tools=[search_web, visit_webpage],
    )
)

trace = agent.run("Which agent framework is the simplest?")
print(trace.final_output)

model_id follows the any-llm provider syntax (provider:model). Set the relevant API key (e.g. MISTRAL_API_KEY, OPENAI_API_KEY) in your environment.

Use MCP tools

from tinyagent import TinyAgent, AgentConfig
from tinyagent.config import MCPStdio

agent = TinyAgent.create(
    AgentConfig(
        model_id="mistral:mistral-small-latest",
        instructions="Use the available tools to answer.",
        tools=[
            MCPStdio(command="uvx", args=["duckduckgo-mcp-server"]),
        ],
    )
)

trace = agent.run("What is the capital of Pennsylvania?")
print(trace.final_output)

Tracing

Every agent.run(...) returns an AgentTrace with the final output, the spans, token counts, and cost.

trace = agent.run("...")
print(trace.duration)
print(trace.tokens)
print(trace.cost)
for span in trace.spans:
    print(span.name, span.attributes)

Callbacks

Subclass Callback to observe or control execution. Each hook receives a Context and returns it, optionally mutating shared state.

from tinyagent.callbacks import Callback, Context

class LimitToolCalls(Callback):
    def before_tool_execution(self, context: Context, *args, **kwargs) -> Context:
        context.shared["count"] = context.shared.get("count", 0) + 1
        if context.shared["count"] > 5:
            raise StopIteration("Too many tool calls")
        return context

See AgentCancel for cancellation that preserves the trace.

Serve as a service

from tinyagent.serving import MCPServingConfig

agent = TinyAgent.create(...)
handle = await agent.serve_async(MCPServingConfig(port=8080))

A2A serving is available with the [a2a] extra.

Running in Jupyter

import nest_asyncio
nest_asyncio.apply()

License

Apache 2.0.