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.
Metadata
Release files for mozilla-ai-tinyagent 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mozilla_ai_tinyagent-0.1.1.tar.gz | 131.4 kB | With provenance | Details for mozilla_ai_tinyagent-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mozilla_ai_tinyagent-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for mozilla_ai_tinyagent-0.1.1-py3-none-any.whl |
Total release size: 193.2 kB
Release files / mozilla_ai_tinyagent-0.1.1.tar.gz
| Download URL | mozilla_ai_tinyagent-0.1.1.tar.gz |
|---|---|
| Size | 131.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a15cb18c7e56c1b8a6b3670540e58fc65f6d156457855a600ea14ff8b4cfc322
|
|
BLAKE2b-256 checksum How to use checksums |
129cb39db097e64c5d12e64c51fb28b97a9ca601b550d892d829166a75509a64
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 29, 2026.
Transparency logRelease files / mozilla_ai_tinyagent-0.1.1-py3-none-any.whl
| Download URL | mozilla_ai_tinyagent-0.1.1-py3-none-any.whl |
|---|---|
| Size | 61.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dae0bedde71fc2edf68036523d66f008612f5070bab8ef027964574c30c22f4b
|
|
BLAKE2b-256 checksum How to use checksums |
4d69e9bffd45ff74853a4277d126f1050be5891c717830d2ec2a1be4ceb67094
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 29, 2026.
Transparency logSecurity for mozilla-ai-tinyagent 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mozilla_ai_tinyagent-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.