agent-adapter

The agentic framework that runs your tools anywhere, safely.

Write a tool once, as a plain Python function. Use it in any agent framework, any backend or on its own, with approvals, budgets, cost and traces built in.

_{Watch it in 29 seconds · share it}

Version 1.1.0 · Python 3.11+ · Apache-2.0 · 21 frameworks and engines · Coverage gate 90%

Quickstart · Why · How it works · Tour · Viewer and chat · Install · Docs · Use cases · Agent skill · Prompt for any AI

Agent Adapter is an agentic framework built around your tools: write each tool once, run it in
LangChain, CrewAI, ADK or 18 more, from any backend or language, safe, priced and traced.

It is an open-source, framework-independent Python SDK. It turns your functions into LLM
tools, checks their schemas once at startup, and runs every call through one
executor that applies approval, budgets, guards, caching and cost tracking. The core
depends only on pydantic. Every framework is an optional extra, imported lazily.

No agent framework is needed: a FastAPI service calling an LLM gets tools, approvals,
budgets, cost, cache and context compression directly. The adapter can also be your
framework: run_tool_loop with your own model is the agent loop, and Flow is the graph.

Let your AI set it up. Add the agent skill to Codex, Cursor, Copilot, Gemini CLI or 60+ more agents with
npx skills add VeloceAI/agent-adapter --skill agent-adapter -a <agent> (e.g. -a codex), or in Claude Code /plugin marketplace add VeloceAI/agent-adapter.

Quickstart

import agent_adapter as aa


@aa.tool
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b


print(aa.call(add, a=1, b=2))  # 3: validated and guarded by the default executor

This is examples/hello.py, which the test suite runs. @aa.tool registers the function
on the default registry; aa.call runs it through the default executor. From async code
(FastAPI, ...) use await aa.acall(add, a=1, b=2). The full walk-through is the
Quickstart.

Why Agent Adapter

Each framework has its own tool format, its own idea of approval and no shared view of cost.
Change framework, or run two, and the rules are rewritten. Agent Adapter keeps them in one place.

How it works

Every call, from any source, goes through the same executor. Frameworks, protocols and
model APIs are thin adapters around it, so the safety rules hold everywhere.

flowchart LR
  subgraph IN["Where calls come from"]
    A["your code<br/>run · run_sync · call"]
    B["model APIs<br/>OpenAI · Gemini · Anthropic"]
    C["agent frameworks<br/>LangGraph · ADK · CrewAI · 16 more"]
    D["protocols<br/>MCP · HTTP · A2A · AG-UI"]
  end
  R[("Registry<br/>your functions<br/>as checked tools")]
  subgraph EX["Executor: one pipeline for every call"]
    direction TB
    V["validate arguments"] --> G["guards and budgets"]
    G --> P["approval<br/>one-use decision"]
    P --> K["cache"]
    K --> T["run the tool<br/>retry · timeout"]
    T --> L["ledger · events"]
  end
  O["outputs<br/>result · cost · trace<br/>run viewer · OpenTelemetry"]
  IN --> R --> EX --> O

A tour in code

Human approval that survives a restart

A confirm=True tool runs only after a one-use approval. Park the call in SQLite and
resume it later, in any process (examples/hello_approval.py):

@aa.tool(confirm=True)
def refund(order_id: str, amount: float) -> str:
    """Refund an order."""
    return f"refunded {amount} on {order_id}"


executor = aa.configure(approval=aa.DeferredApproval.sqlite(folder / "approvals.db"))
try:
    aa.call(refund, order_id="o-7", amount=500)
except aa.ApprovalPending as pending:
    approval_id = pending.approval_id  # store it, show it to a reviewer
# ... later, in any process that opens the same file:
result = executor.resume_sync(approval_id, True, decided_by="ana")
print(result.value)  # runs once; a second resume is refused

Budgets, limits, cost and logs

executor = aa.Executor(
    registry,
    hooks=[aa.LoggingHook(), aa.BudgetHook(0.50)],  # stop a run past $0.50
    ledger=aa.Ledger(),  # priced per call, per run
    limits=aa.RunLimits(max_calls=20),  # at most 20 tool calls a run
)

A flow: decide, fan out, join, pause

A Flow is a validated graph over one pydantic state. The local FlowRunner runs it; the
same graph compiles to LangGraph and ADK (examples/first_flow.py):

flow = (
    Flow("support", state=Ticket)
    .node("classify", classify)
    .node("policy", Call("lookup_policy", args=lambda t: {"category": t.category}, into="reply"))
    .node("escalate", escalate)
    .route(
        "classify",
        Route(
            lambda t: "policy" if t.category == "refund" else "escalate",
            targets=["policy", "escalate"],
        ),
    )
    .end("policy", "escalate")
)
result = run_sync(FlowRunner(Executor(registry)).run(flow, {"text": "I want a refund"}))

flowchart LR
  S((start)) --> classify
  classify -- "refund" --> policy["policy<br/>tool: lookup_policy"]
  classify -- "other" --> escalate
  policy --> E((end))
  escalate --> E

Map fans one node out over a list, Join merges the branches, Merge rules say how
parallel writes combine, and pause=True on a node waits for a person. See
Flows and Chat flows by example.

Your own agent loop

run_tool_loop drives any model port through tool calls until it answers. Every call goes
through the executor, so approval, cache, budgets and cost apply (examples/tool_loop.py):

model = CallableModel(my_llm, provider="host", model="router-v2")  # or OpenAIModel, ...
result = await run_tool_loop(model, registry, question, executor=executor)
print(result.finish, result.steps, result.final.text)

The same tools over MCP and HTTP

from agent_adapter.integrations.mcp import mcp_server
from agent_adapter.server import bearer_auth, create_app

server = mcp_server(registry, name="shop-tools")  # MCP, stdio or HTTP
app = create_app(registry, authenticate=bearer_auth(TOKENS))  # REST + SSE + OpenAPI, MCP at /mcp

The TypeScript client, A2A and AG-UI are in Connect anywhere.

See your runs and chat with your agent

Record runs with agent_adapter.viewer.record(executor), then open the local viewer:
a run list, a navigable flow graph, a timeline, events with filters, state and cost. Start
it with an agent and the same page becomes a chat, like a playground for any framework:

agent-adapter ui                                         # browse recorded runs
agent-adapter ui --agent app:chat                        # chat with any agent
agent-adapter ui --model app:model --tools app:registry  # the built-in tool loop

It binds 127.0.0.1 only and opens with a private token link. Try both live, nothing to
install: the run viewer demo
(graph, replay, timeline, compare) and the chat demo.

Attach anywhere

Safe by default

Features

The full list, with a guide for each feature: Features. Next: the Roadmap.

Install

Requires Python 3.11 or later.

pip install agent-adapter                 # core (pydantic only)
pip install "agent-adapter[openai]"       # + the extras you need

Pins per extra: Install, Support matrix.

Command line

Project layout

agent_adapter/   the package: one sub-package per layer (see "How it works")
examples/        runnable examples; the test suite runs them, the docs include them
docs/            the MkDocs site: get started, how-to, concepts, reference, demos
tests/           pytest suite mirroring the package, plus docs, example and JS tests
clients/         the TypeScript client for the HTTP tool server
scripts/         check.py (every gate) and the generators for docs and guides

Working on the code itself? CODEBASE.md is the map: architecture, where
everything lives, the rules, the gates and the generated files.

Documentation

The site is agent-adapter.veloceai.in; its source is
docs/ (MkDocs Material, mkdocs build --strict). Start with How-to → Attach anywhere, or
build a whole app with the golden path tutorial. Before
production, read the threat model and the
API stability policy.

Development

pip install -e ".[dev,docs,openapi]"   # openapi brings httpx, which mypy checks against
python scripts/check.py

scripts/check.py runs every gate in order and stops at the first failure: pytest with
coverage (≥ 90 %, warnings are errors), ruff check, ruff format --check, mypy --strict
and mkdocs build --strict. The nox sessions in noxfile.py run the same suite per Python
version and per integration. Releases follow docs/contributing/release.md;
changes are listed in CHANGELOG.md.

Licence

Apache License 2.0. See LICENSE and NOTICE. Copyright 2026 Veloce AI.