Repository navigation
v1.1.0
The first public release: open source under Apache-2.0 and published on PyPI.
Added
- Guardrails.
PIIGuard: a dependency-free guard hook for emails, phone numbers, cards
(Luhn), IBANs (mod-97) and API keys or secrets. It blocks, redacts tool results and model
replies, or sends flagged tool calls to one-use approval (confirm=guard.confirm). It fails
closed and never logs content. CallableGuard(fn)for any guard service;PresidioGuard(extrapresidio) and
NemoGuard(extranemo);ContentGuard,TextGuardandGuardVerdictto write your own.- Multi-agent.
agent_tool(agent, ...): any agent (aLoopAgent, afn(task, ctx), or a
chat agent viachat_agent_task) becomes a registry tool that runs in the calling run. Cost,
budgets, limits, approvals and events roll up, withparent_idlinks.AgentDepthExceeded
caps nesting (max_depth, default 3). handoff(...)andHandoffModel: hand the conversation to another agent; its answer ends
the tool loop.- Sub-flows.
SubFlow(flow, input=, into=)runs another flow as one node. Fields map in
and out under the parent's merge rules. A pause or approval inside the child pauses the
whole run, and resume continues from where it stopped. Sub-flow cycles and field types are
checked atvalidate(). Mermaid draws a subgraph, and the run viewer opens a sub-flow node
(⊞ open, keyso/u). - Node cache.
Flow.node(..., cache=NodeCache(ttl=, key=, reads=, scope=))reuses a
node's updates from the executor's cache port. Entries are signed with the runner's
checkpoint key. A node with a pause gate or a tool that needs approval is never cached. A
hit emits the newnode.cachedevent. - Context windows. Price table
2026-11-05:context_windowandmax_output_tokenscaps
(with the vendor page in a newsourcefield) for every cited OpenAI, Gemini and Claude
row, so percent compression policies need no setting for them. - Price rows for gpt-5.6-sol/-terra/-luna, gpt-5.5, gpt-5.4-mini, gpt-6-astra, gpt-6.1-sol,
gpt-6.1-terra, gpt-6-luna, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3.1-flash-lite,
and Claude Fable 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5 (with 5m and 1h cache-write
prices). ModelCaps.max_output_tokensandModelCaps.prompt_window(); percent compression applies
to the window less the reply ceiling.- Model recipes. Amazon Bedrock (Converse), Azure OpenAI, Mistral, Groq and OpenRouter as
CallableModels, with usage, prices and typed errors (docs: Model recipes). - Send traces. Langfuse, Arize Phoenix and OpenLLMetry over the OTel sink (docs: Send
traces). agent-adapter doctorchecks optional backends from a pluggable list: Presidio and NeMo
guards, the OpenTelemetry SDK and OTLP exporters.- A spec-drift test keeps the docs, the LLM guide and the public API in agreement.
- Evals.
agent_adapter.evals:run_eval(target, cases, graders)runs each case as its own
run on your executor (approvals, budgets, ledger, events, recorder) and returns an
EvalReportwith per-case, per-tag and per-grader totals, cost and timing,compare()for
regressions, andto_junit(),to_markdown(),to_json(). Targets: anyfn(input), a chat
agentfn(message, session),FlowTarget,ToolLoopTarget. Graders:exact,contains,
regex,json_schema,tools_called,max_cost,max_latency,code_check,all_of, and
LLMJudge(model, rubric)on your own model. Cases saved by the chat page load unchanged. agent-adapter eval TARGET CASES:--grader,--min-score,--junit,--markdown,--json,
--baseline; exits 1 below the score, on any case error, or on a regression.- Pytest plugin:
@pytest.mark.eval_cases("cases.jsonl")runs a test once per case
(eval_casefixture);assert_evalfails with each grader's reason and the run id. - Evals in the viewer.
agent-adapter uihas an Evals tab: every saved report with its
score, pass/fail, cost and time, per-tag and per-grader totals; each case with its input,
expected value, output, every grader's score and reason, and a link to its run; two
reports side by side with regressions marked (EvalReport.compare). Save reports with
run_eval(..., save_to=),save_report(report, folder)oragent-adapter eval --save;
agent-adapter ui --evals FOLDERpicks the folder (default.agent_adapter/evals). - Eval case results keep the case's
inputandexpectedtext. - Grader specs on the command line:
regex=,json-schema=,tools=,max-cost=,
max-latency=(module:attris always your own grader).--min-pass-rate,--no-content
(run_eval(capture_content=False)) andLLMJudge(trust_passed=). - Memory.
agent_adapter.memory:MemoryPort,SQLiteMemory(one file, FTS5 keyword
search with a LIKE fallback, optional vector search through anyEmbeddingPort),
CallableMemory, and lazyMem0Memory,ZepMemoryandGraphitiMemory(extrasmem0,
zep,graphiti).memory_tools()addsremember,recallandforgettools whose scope
comes from the context, never from the model. Searches never cross users. - Memory retention and privacy:
retention_daysandexpires_atare enforced on read and
purged on write;export(scope)serves data requests;delete(scope=MemoryScope(user_id=...))
erases a user. ToolContext.user_id: the authenticated end user, set by the host (Executor.context(user_id=)).- Events
memory.added,memory.searched,memory.deletedandmemory.exported(counts only). - Retrieval (RAG).
agent_adapter.retrieval:RetrieverPort,Document(id, text, score,
source),CallableRetriever, an in-memoryEmbeddingRetriever(scope_keyisolation),
LlamaIndexRetrieverandLangChainRetriever, andretriever_tool: a registry tool whose
results carry sources for citations, with host-setkand filters that every result is
re-checked against. Eventsretrieval.searchedandretrieval.failed(counts and ids; texts
only withcapture_content). agent-adapter doctoralso reports the memory extras and the LlamaIndex and LangChain
retrievers.- Chat memory across chats.
serve(..., memory=, user_id=, memory_save="none"|"summary"|"facts", memory_every=, recall_k=)andagent-adapter ui --memory sqlite:PATH --user NAME --memory-save ... --memory-every N --recall K. Each turn recalls the user's records from other chats as
session.memories(the built-in loop: a system note). Saving is opt-in: by the model, or by
the agent'ssave_memories.ctx.user_idis the chat's user, chats are kept per user, and
the inspector has a Memory tab to see and delete the user's records. - Approval memory in
agent_adapter.approval:approval_contextshows similar past
decisions (counts, deciders, outcomes; never argument values or secret fields) on chat
approval cards, in the Runs approvals desk, and inGET /approvals/{id}for approvers (the
TypeScriptApproval.context).propose_rulessuggestsfield == value/field <= limit
confirm rules;accept(rule, accepted_by=...)gives the code and config to commit, and the
confirm=callable. Nothing is ever approved from memory. - Viewer:
memory.*events show asmemoryspans in the timeline; run summaries carry a
memorycount, and a top-levelretrieval.failedcounts as a failure. agent_adapter.chat: the chat agent contract (ChatMessage,ChatSession,Attachment,
ChatAgent,ChatReply) in one place, used by the chat page and evals.agent_adapter.viewer
andagent_adapter.viewer.chatre-export the same classes.- Memory scopes:
thread_scopeis opt-in;scope_from_contextno longer gives anonymous
callers memory; SQLite erasure leaves no text in the file. - Crash-safe runs.
FlowRunner(checkpoints=store, checkpoint_key=KEY)saves a sealed
checkpoint after every superstep and logs every tool call.runner.recover(flow, run_id)and
runner.recover_all(flow)continue a crashed run on any worker, and calls that finished replay
instead of running again. A call left in doubt runs again only for anidempotent=Truetool or
withrerun_in_doubt=True; otherwiseRecoveryNeedsDecisionis raised. Two workers never both
continue a run (CheckpointConflict), and a changed graph refuses to recover.
idempotency_key()gives each call a key that is the same on every worker and recovery. run_tool_loop(..., run_id=, checkpoints=, checkpoint_key=)andrecover_tool_loop(...)do
the same for the tool loop.- Checkpoint stores in
agent_adapter.exec.checkpoints:MemoryCheckpointStore,
SQLiteCheckpointStore,RedisCheckpointStore(extraredis),SQLAlchemyCheckpointStore
(extrasqlalchemy), and theCheckpointStoreprotocol. New errorsCheckpointNotFound,
CheckpointConflict,CheckpointStoreCorrupt,RecoveryNeedsDecision; new events
checkpoint.savedandrun.recovered; the viewer's run summary carriesrecovered: true. - Durable engines. Run a
Flowon Temporal (extratemporal) or DBOS (extradbos). Each
superstep is one activity or step through your executor, so approvals, budgets, cache, ledger
and events apply; a retried step replays finished tool calls from the checkpoint store, and
runs carry aRunIdentity. Approvals stay in your approval store: a Temporal update or
signal, or a DBOS message (notify), only wakes the run to re-check the store, and the stored
decision is used once; a timeout records a denial.agent_adapter.integrations.temporal
(flow_worker,start_flow,notify,pending,result) and
agent_adapter.integrations.dbos(DbosFlows), over the sharedDurableFlows.
FlowRunner.inspect()andFlowRunner.on_superstepsupport them. - Sandboxed code.
agent_adapter.sandbox:SandboxPortandSandboxResult;
DockerSandbox(the docker CLI, no SDK:--network none, read-only root,--cap-drop ALL,
no-new-privileges, a non-root user, pids/memory/cpu limits, a noexec tmpfs, removed on
timeout);CallableSandboxfor E2B, Modal, Daytona or any service;LocalSubprocessSandbox
for development only (refuses withoutallow_unsafe_local=True, warns on every run); and
code_tool, a registry tool that always needs approval (no opt-out), with host-set time,
output, network and file limits. Produced file names are checked on the host. New events
sandbox.started,sandbox.finishedandsandbox.failed(sizes and exit codes; code and
output only withcapture_content).agent-adapter doctorreports whether Docker can run. - Team budgets.
BudgetHook(scope="user"|"principal"|"team", per="day"|"month", scope_key=, store=)caps spend per user, team or everything, per UTC day or month, shared
across processes: it reserves an estimate atomically before each model call, settles the real
cost after and releases on failure. Stores:MemoryBudgetStore,SQLiteBudgetStore,
RedisBudgetStore,SQLAlchemyBudgetStore(agent_adapter.hooks.builtin.budgets).
GET /budgetand/budget/{scope}on the HTTP server (own scope; approvers any key),
budget.reserved/budget.exceededevents, the viewer marks runs a budget refused, the
TypeScript client'sbudget(), and doctor rows. - Streaming.
PartialOutputevents carry the structured output parsed so far (OpenAI,
Gemini, Anthropic,CallableModel(stream_fn=));run_tool_loop(on_event=)gets tool-call
deltas, partial output andStreamDone; stream event types are importable from
agent_adapter.models. A chat agent or eval target may yieldToolCallDeltabetween text
chunks. - Chat page: tool arguments appear in a draft tool card while the model streams them (masked,
cut to 2 KB). - Viewer: search across runs (tool, flow, node, model and error names, run ids,
status:,
tag:, captured content) and run tags stored in atags.<run key>.jsonsidecar per run, set
from the run header.agent-adapter ui --import traces.jsonand
agent_adapter.viewer.import_otlp: OTLP JSON GenAI spans become viewer runs (parsed only,
size-limited). - Framework templates.
agent-adapter init pydantic-ai | adk | agno | strands | crewai: a
starter with registry tools, aconfirm=Truetool behind an approval port, a budget and the
run recorder. It runs offline; setAGENT_MODELto run the agent. agent-adapter migrate PATH. A read-only scan (Pythonast; it never imports or writes)
for LangChain, CrewAI, OpenAI Agents, ADK, Pydantic AI, LlamaIndex, smolagents, Agno and
Strands tools and raw OpenAI or Anthropic schemas;--diffprints a suggested patch to
@registry.tool/registry.wrapwith the matching bridge;--frameworkfilters.- Policy file.
agent_adapter.policy.load_policy(path)reads one YAML, TOML or JSON file (or
a dict) that sets, per tool, team, user and environment (AA_ENV): allowed tools
(default: deny), approvals (confirm: trueor a safe condition such asamount > 100),
guards, budgets, rate limits, run limits, memory retention and save rules, and sandbox
requirements.policy.apply(executor)builds them from the existing hooks and approval path,
so the tool loop, every integration, MCP and the HTTP server obey it. A policy only makes
things stricter: it never removes an approval, unknown keys fail at load with the file, line
and key, and the two relaxations needallow_relax=True.policy.explain(tool, ctx), the
viewer's Tools tab andagent-adapter policy check FILEshow the effective rules.
Executor(policy=)is the new seam; it is enforced whateverreplace(...)changes, and
Executor.hookslists only the hooks you passed. - Audit log.
agent_adapter.audit:audit(executor, folder=, key=)keeps a signed,
hash-chained JSONL log of approvals (requested, decided, consumed, denied, expired), guardrail
blocks and redactions, budget stops, memory adds, deletes and exports, sandbox runs, recovered
runs and your ownaudit.<name>events (recorded asapp.<name>), never arguments or
content; records are written on a background thread.verify()detects edits, deletions,
reordering and truncation, andverify --anchorcatches rollbacks;export()andagent-adapter audit verify|exportgive JSONL or
CSV;CallableAuditStoreships records to a SIEM or bucket.fail_closed=Trueblocks calls
before their side effect when a record cannot be written;verify,read_entriesand
export_tostream. New eventsapproval.expiredandguardrail.redacted;
approval.decidedcarriesedited; memory events carryscope_kind. Redis and DynamoDB
TTL expiries are recorded at resume. - Adoption pack. A golden-path FastAPI support desk (
examples/golden_path/): confirmed
refunds with a SQLite approval store, a daily budget per user, PII guards, memory across
chats, cited help answers, a crash-safe flow, recorded runs, and eval cases run by
agent-adapter evalas the CI gate (docs: Tutorial: the golden path). scripts/bench_overhead.pymeasures the executor's per-call overhead over a direct call, per
feature; measured numbers are in the Performance guide.- A threat model page (assets, trust boundaries, what the adapter enforces and what it does
not) and an API stability policy for 1.x (public surface, semver rules, deprecation,
experimental markers). - Production → evals loop.
agent_adapter.evals.cases_from_runsand
agent-adapter eval cases-from-runs RUNS_DIR --out cases.jsonlturn recorded runs (captured
content only; others are skipped with the reason) into eval cases withsource_run; the Runs
view gets "Save as eval case" and, on failed runs, "Turn into regression case", appending to
the chat'seval_cases.jsonl. - Opt-in content on native events: a sink with
wants_content = True(the run recorder under
capture_content=True) gets tool arguments and results, model messages, and a flow's input
and final state; other sinks get none, and content is not built for them. Content is taken
after guards (arguments ontool.finished, messages onllm.finished), secret-named keys
and secrets and PII inside text are masked,confirmtools' arguments are never sent, and
their results needcapture_confirm_content=True. - Cost advisor.
agent_adapter.evals.advisor.advise(target_factory, cases, graders, candidates=, baseline=)runs your evals on the baseline model, then tries each cheaper
candidate in one flow node or stage at a time, and reports the cheapest model per step that
keeps the score (min_score_ratio, default 0.98), with cost and latency deltas from the
ledger.max_spend=caps the candidates' spend and stops early.report.mappingholds only
verified advice and is never applied for you:apply_mappingbuilds aStepModelsport forFlowRunner(model=...)or
run_tool_loop(docs: Cut model costs per step). Ledger entries
of model calls made inside a flow node carrymetadata["node"]. - Docs: a production checklist (approvals, budgets, guardrails, tracing, evals in CI,
caching, logs, viewer and server security).
Fixed
- The ADK starter template runs offline without
google-genai;adk_tools()imports it only
when ADK asks for a tool declaration. - The viewer keeps runs started within one clock tick in order (newest first), and rotation
deletes the oldest of them. SQLAlchemyBudgetStore.aclose()disposes of the running loop's engine, like the approval
and checkpoint stores.
Changed
-
Licensed under Apache-2.0 (
LICENSE,NOTICE; PEP 639license = "Apache-2.0"). The
package installs from PyPI: thePrivate :: Do Not Uploadclassifier and the
internal-index install steps are gone. The TypeScript client is Apache-2.0 too (still
private). -
agent-adapter doctor: public PyPI or a mirror as the index isok; an
extra-index-urlorUV_EXTRA_INDEX_URLis a warning, no longer an error. -
Live-provider checks (the OpenAI usage formula, Anthropic structured output, the
google-genaiwire keys) were run by the maintainer before release. -
Prices.default().versionis now2026-11-05;claude-stays caps-only for Claude ids
without a row. -
The LangGraph and ADK flow compilers raise
FlowCompileErrorforSubFlownodes. -
The
devextra addspytest-xdistandpytest-testmon. -
The optimiser's
EvalCase,Score,load_casesandoptimiser.gradersnow live in
agent_adapter.evals; the optimiser names are re-exports, so existing imports keep working. -
agent-adapter doctorhelp names the optional-backend checks. -
graders.all_offails closed:passed=Falsewhen a part errors or does not grade. -
agent-adapter ui --chat-diralso works without chat (it is where Runs-view eval cases go). -
The eval pytest plugin is opt-in (
-p agent_adapter.evals.pytest_plugin, or
pytest_pluginsin aconftest.py), so installing the package changes no pytest run.