Agent Assembly Examples

Runnable examples showing how to integrate Agent Assembly with real AI agent frameworks, enforce policies, gate approvals, capture audit traces, and control runtime budgets.

What is Agent Assembly?

Agent Assembly is a multi-layer AI agent governance platform that intercepts, inspects, and enforces policies on tool calls made by AI agents — without requiring you to rewrite your agent code. It works via three independently deployable layers: SDK wrappers (Python, Node.js, Go), a sidecar MitM proxy, and kernel-level eBPF probes. A central gateway holds the agent registry, evaluates policies, tracks budgets, and exposes gRPC and HTTP APIs for observability and control.

Official docs & SDKs

These examples are the runnable companion to the official documentation and the language SDKs. Learn by running small, framework-specific examples for Python, Node.js/TypeScript, Go, policy enforcement, approvals, audit, trace, and runtime workflows — then go deeper in the docs.

Resource	Link
Documentation hub	https://ai-agent-assembly.github.io/agent-assembly-docs/
Core runtime & CLI	agent-assembly
Python SDK	python-sdk
Node.js / TypeScript SDK	node-sdk
Go SDK	go-sdk

Who is this repo for?

• Application developers who are adding Agent Assembly to an existing Python, Node.js, or Go agent application.
• Platform engineers who are deploying Agent Assembly as a runtime governance layer.
• Evaluators who want to understand policy enforcement, approval gates, audit tracing, and budget controls through working code before committing to adoption.

Quick navigation

You want to…	Start here
Use Python + LangChain	python/
Use Node.js / TypeScript + LangChain	node/
Use Go	go/
Explore policy enforcement	scenarios/policy-enforcement/
Understand approval gates	scenarios/approval-gates/
See audit/trace output	scenarios/audit-trace/
Enforce budget guardrails	scenarios/budget-limits/
Run with a local sidecar runtime	scenarios/sidecar-runtime/
Read core concepts first	docs/concepts.md
Choose the right example	docs/choosing-an-example.md

Advanced scenarios: observability and runtime controls

The scenarios/ directory contains cross-language examples that demonstrate Agent Assembly's runtime governance features. These are the fastest path to understanding what Agent Assembly does at the product level — no framework setup required, no API keys needed.

Scenario	What it demonstrates	Quick start
audit-trace	Governed tool calls producing allow, deny, and approval_required audit records	python scenarios/audit-trace/python/agent.py
budget-limits	Budget guardrails blocking tool calls when a session cost ceiling is hit	python scenarios/budget-limits/python/agent.py
sidecar-runtime	Running agents against a local Agent Assembly gateway via Docker Compose	bash scenarios/sidecar-runtime/scripts/start.sh

All three scenarios include Python and Node.js examples. They run offline by default — no live gateway needed unless you opt into the Docker Compose path.

Framework examples

Each language directory contains framework-specific examples that wire Agent Assembly into a real AI agent framework. The per-language indexes (python/, node/, go/) hold the full setup and run instructions; the catalog below is the shared cross-language view.

Python

Example	Framework	What it demonstrates
python/langchain-basic-agent/	LangChain	Wire Agent Assembly SDK into a basic LangChain agent
python/openai-agents-sdk/	OpenAI Agents SDK	Govern tool calls made by an OpenAI Agents SDK agent
python/llamaindex-tool-policy/	LlamaIndex	Enforce tool-level allow/deny policies with LlamaIndex
python/custom-tool-policy/	—	Write a custom Python tool wrapper with the SDK
python/langchain-research-agent/	LangChain	ReAct research agent with budget, egress allowlist, and credential-leak blocking
python/crewai-research-crew/	CrewAI	Multi-agent crew with delegation tracking, file-write approval, and shared budget
python/langgraph/	LangGraph	Node-level governance on a compiled StateGraph, blocking a destructive tool mid-graph
python/pydantic-ai/	Pydantic AI	Tool-call governance driven offline by TestModel (allow / deny / pending)
python/google-adk/	Google ADK	Scripted offline tool trajectory governing BaseTool.run_async (no cloud creds)
python/haystack-tool-policy/	Haystack	Govern a real Haystack agent via the native adapter — real Tool.invoke allow/deny through a ToolInvoker
python/smolagents-tool-policy/	Smolagents	Govern real smolagents.Tool calls via Tool.__call__, blocking a destructive tool offline (no model creds)
python/agno-tool-policy/	Agno	Govern real Agno FunctionCall.execute tool calls (allow / deny / pending); offline, no model creds
python/microsoft-agent-framework-tool-policy/	Microsoft Agent Framework	Govern agent_framework.FunctionTool.invoke (allow / deny / pending); offline mock + live paths

Node.js / TypeScript

Example	Framework	What it demonstrates
node/langchain-js-basic-agent/	LangChain.js	Tool governance hooks in a LangChain.js-style agent
node/openai-node-tool-policy/	OpenAI Node SDK	Policy enforcement using OpenAI function-calling format
node/custom-tool-policy/	—	Minimal SDK usage — no agent framework needed
node/vercel-ai/	Vercel AI SDK	Governing Vercel AI SDK tool() calls with withAssembly
node/langgraph-js/	LangGraph.js	Governing tool calls inside a LangGraph.js-style state machine
node/mastra/	Mastra	Governing Mastra createTool calls with withAssembly

Go

Example	Framework	What it demonstrates
go/basic-agent/	—	Minimal Go SDK initialization and a governed tool call
go/tool-policy/	—	Explicit allow/deny policy behavior around Go tool execution
go/langchaingo/	LangChainGo	Governing a LangChainGo agent's tool calls with Agent Assembly
go/cli-runtime-integration/	—	Integrating the aasm CLI runtime sidecar with a Go agent

Prerequisites

Install the prerequisites for the ecosystem you want to run.

Python examples

python3 --version   # requires Python >= 3.12
pip install uv      # optional but recommended

Node.js / TypeScript examples

node --version    # requires Node.js >= 20 LTS
pnpm --version    # install via: npm install -g pnpm

Go examples

go version   # requires Go >= 1.22

Agent Assembly runtime (all examples)

Each example sub-project documents which Agent Assembly component it requires (SDK version, gateway address, sidecar config). See the sub-project README.md for the exact setup.

Verifying examples locally

Every example is verified on each pull request by the verify-python, verify-node, verify-go, and verify-scenarios GitHub Actions workflows. Run the same checks locally before opening a PR:

Python — per example under python/:

cd python/<example>
uv sync --extra dev
uv run pytest tests/

Node.js / TypeScript — per example under node/:

cd node/<example>
pnpm install
pnpm test

Go — per example under go/:

cd go/<example>
go test ./...

Scenarios — cross-language smoke runs under scenarios/:

python scenarios/<scenario>/python/agent.py
node   scenarios/<scenario>/node/agent.js

Security

No secrets are ever committed to this repository.

• Configuration files that require API keys or connection strings provide a .env.example template only.
• Copy .env.example to .env, fill in your values, and keep that file local — .env is listed in .gitignore.
• Never paste real credentials into a file tracked by git.

Compatibility

Each example sub-project pins or documents the Agent Assembly SDK and gateway version it was written and tested against. Check the sub-project README.md for the requires: block before running.

Contributing an example

1. Pick a directory: python/, node/, go/, or scenarios/.
2. Create a sub-directory named after the framework or scenario (e.g. python/langchain-basic-agent/).
3. Add a README.md inside the sub-directory with:
   • What it demonstrates (one paragraph)
   • Prerequisites (language version, Agent Assembly version, any API keys needed)
   • Setup (git clone, install deps)
   • Run (exact command and expected output)
   • Troubleshooting (common errors and fixes)
4. Add a .env.example if the example needs any configuration.
5. Open a PR with title [AAASM-XXXX] <GitEmoji> (<scope>): <summary>.

See docs/concepts.md for background on how Agent Assembly works before building an example.

Repository layout

agent-assembly-examples/
  README.md                     ← you are here
  LICENSE                       ← Apache-2.0
  .gitignore
  docs/
    concepts.md                 ← Agent Assembly core concepts
    choosing-an-example.md      ← decision guide: which example to run first
  python/
    README.md                   ← Python examples index
    langchain-basic-agent/      ← LangChain · OpenAI Agents SDK · LlamaIndex ·
    ...                            custom · langchain-research · crewai ·
    ...                            langgraph · pydantic-ai · google-adk ·
    ...                            smolagents-tool-policy
  node/
    README.md                   ← Node.js / TypeScript examples index
    langchain-js-basic-agent/   ← LangChain.js · OpenAI Node · custom ·
    ...                            vercel-ai · langgraph-js · mastra
  go/
    README.md                   ← Go examples index
    basic-agent/                ← basic · tool-policy · langchaingo ·
    ...                            cli-runtime-integration
  scenarios/
    README.md                   ← Cross-language scenario examples index
    policy-enforcement/         ← Allow/deny policy enforcement scenario
    approval-gates/             ← Human-in-the-loop approval gates scenario
    audit-trace/                ← Governed tool calls + audit record inspection
    budget-limits/              ← Budget guardrails and cost ceiling enforcement
    sidecar-runtime/            ← Local Agent Assembly runtime via Docker Compose
  .github/
    workflows/
      README.md                 ← CI workflow documentation