any-agent: Instructions file for Codex

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

CLAUDE.md is a symlink to this file. Always edit AGENTS.md directly; never modify CLAUDE.md.

Project Status: Soft Deprecation

any-agent is in soft deprecation. It is still published and maintained, but:

• Bug fixes and security fixes only. No new features are planned.
• New projects should use mozilla-ai-tinyagent (PyPI: mozilla-ai-tinyagent) if they only need the core agent loop. That package is where the distilled agent loop now lives.
• Reach for any-agent when you specifically need to run or evaluate agents across multiple frameworks (Agno, Google ADK, LangChain, LlamaIndex, OpenAI Agents SDK, smolagents, TinyAgent) under one API.

Before starting feature work, check whether the change belongs in tinyagent instead. See the banner in README.md for the user-facing statement.

Where to Look First

• README.md: high-level usage and supported frameworks.
• CONTRIBUTING.md: canonical dev setup, test matrix, and contribution workflow.
• pyproject.toml and .pre-commit-config.yaml: formatting/lint/typecheck configuration.
• docs/: MkDocs documentation site (configured by mkdocs.yml).

Project Structure & Module Organization

• src/any_agent/: Core library. AnyAgent is the main entry point; AgentConfig and AgentFramework define config.
• src/any_agent/frameworks/: One module per supported framework (agno, google, langchain, llama_index, openai, smolagents, tinyagent). Each implements AnyAgent's abstract methods via lazy imports to keep optional dependencies isolated. The tinyagent module is a thin shim that delegates to the standalone mozilla-ai-tinyagent package; the loop itself lives there.
• src/any_agent/callbacks/: Callback system with per-framework wrappers (wrappers/) and span generation (span_generation/). Base class is Callback in base.py.
• src/any_agent/tools/: Built-in tools (web browsing, user interaction, final output) plus MCP client integration (mcp/), A2A tools, and Composio integration.
• src/any_agent/tracing/: OpenTelemetry tracing setup plus attribute keys (AnyAgentAttributes, and GenAI re-exported from tinyagent). The AgentTrace / AgentSpan / TokenInfo / CostInfo / AgentMessage types are re-exported from the tinyagent package by agent_trace.py, so both packages share the same classes; otel_types.py re-exports the OTel value types the same way.
• src/any_agent/evaluation/: LLM judge and agent judge evaluators.
• src/any_agent/serving/: A2A protocol and MCP server implementations for serving agents.
• src/any_agent/vendor/: Vendored adapters (langchain_any_llm, llama_index_utils). Excluded from the ruff lint hook (ruff-format still applies) and from coverage.
• src/any_agent/testing/: Test helpers (helpers.py) shipped with the package.
• src/any_agent/utils/: Small shared utilities (cast.py).
• demo/: Standalone Streamlit demo deployed to Hugging Face Spaces. It has its own requirements.txt and is excluded from the ruff lint hook (ruff-format still applies) and from mypy; it is not part of the library.
• scripts/: Repo tooling (convert_to_gitbook.py, generate_api_docs.py, wake_up_hf_endpoint.py), excluded from mypy.
• tests/: unit/, integration/, snapshots/, cookbooks/ (runs the notebooks under docs/cookbook/), docs/ (checks code blocks in the docs via mktestdocs), and assets/ (fixture data: trace JSON and HTML), plus shared fixtures in tests/conftest.py.