al-instrument
Auto-instrument LangChain agents with AgentLattice governance. One command adds identity, authorization, and audit trails to every tool your agent calls.
Install
pip install al-instrument
Requires Python 3.9+. Dependencies: libcst, httpx, agentlattice, langchain-agentlattice.
Quick Start
# See what al-instrument would change (diff to stdout)
al-instrument agent.py
# Apply the changes
al-instrument agent.py --apply
# Apply + register the agent + verify governance wiring
al-instrument agent.py --apply --register --test
The diff is the tutorial. Review the generated code to understand exactly what governance means for your agent.
What It Does
al-instrument runs a five-stage pipeline on your Python file:
1. Analyze
Uses libcst (Concrete Syntax Tree) to find every LangChain tool definition in your code. Three patterns are detected:
# Pattern 1: @tool decorator
@tool
def search_database(query: str) -> str:
"""Search the customer database."""
return db.search(query)
# Pattern 2: StructuredTool.from_function()
search_tool = StructuredTool.from_function(
name="search", func=search_database, description="Search the DB"
)
# Pattern 3: BaseTool subclass
class SearchTool(BaseTool):
name: str = "search"
description: str = "Search the database"
def _run(self, query: str) -> str:
return db.search(query)
Detection is deterministic. No LLM involved. Handles aliased imports (from langchain_core.tools import tool as my_tool).
2. Classify
Each detected tool is classified with an action type and risk level using the {domain}.{verb} taxonomy:
| Domain | Example verbs | Default risk |
|---|---|---|
db |
query, read, write, delete | read/write |
email |
send, read | write |
file |
read, write, delete | read/write |
api |
query, execute | read/write |
code |
execute | write |
web |
query, read | read |
payment |
execute | admin |
system |
execute | admin |
If ANTHROPIC_API_KEY or OPENAI_API_KEY is set, classification uses an LLM for intelligent action type assignment. Without an API key, it falls back to tool.{name} with a default risk level of write.
3. Generate
Transforms your source code using libcst (preserving all comments, formatting, and whitespace):
# BEFORE
from langchain_core.tools import tool
@tool
def search_database(query: str) -> str:
"""Search the customer database."""
return db.search(query)
@tool
def send_email(to: str, subject: str, body: str) -> str:
"""Send an email to a customer."""
return email_client.send(to, subject, body)
agent = create_react_agent(llm, [search_database, send_email])
# AFTER
import os
from langchain_core.tools import tool
from agentlattice import AgentLattice
from langchain_agentlattice import govern
al = AgentLattice(api_key=os.getenv("AL_API_KEY"))
@tool
def search_database(query: str) -> str:
"""Search the customer database."""
return db.search(query)
# AgentLattice governance: read-only database access, auto-approved by default policy
governed_search_database = govern(search_database, al=al, action_type="db.query")
@tool
def send_email(to: str, subject: str, body: str) -> str:
"""Send an email to a customer."""
return email_client.send(to, subject, body)
# AgentLattice governance: external communication, requires human approval
governed_send_email = govern(send_email, al=al, action_type="email.send")
# TODO(al-instrument): Replace tool references in your agent constructor:
# Use: [governed_search_database, governed_send_email]
agent = create_react_agent(llm, [search_database, send_email])
4. Register (optional)
With --register, al-instrument registers your agent with the AgentLattice API and writes the API key to your .env file:
AL_SERVICE_KEY=sk-svc-... al-instrument agent.py --apply --register
You can also pass the key directly:
al-instrument agent.py --apply --register --service-key sk-svc-...
5. Verify (optional)
With --test, al-instrument calls execute_sync() for each action type to verify that governance policies are correctly wired:
al-instrument agent.py --apply --register --test
The verifier checks that each action type gets a policy decision from AgentLattice, confirming that the governance pipeline is live end-to-end.
CLI Reference
al-instrument <file> [options]
Arguments:
file Python file containing LangChain agent code
Options:
--apply Write instrumented code back to the file (default: show diff)
--register Register the agent with AgentLattice (requires --apply)
--test Verify governance wiring (requires --register)
--service-key KEY AL_SERVICE_KEY for registration (default: $AL_SERVICE_KEY)
--agent-name NAME Agent name for registration (default: derived from filename)
--base-url URL AgentLattice API base URL (default: https://agentlattice.com)
--ci CI mode: non-interactive, exit codes only
Idempotency
Running al-instrument on an already-instrumented file is safe. It detects the from langchain_agentlattice import govern import and skips with a message:
File already has AgentLattice governance (govern() imported). Skipping.
Report Output
After every run, al-instrument prints a structured report:
════════════════════════════════════════════════════
al-instrument report
════════════════════════════════════════════════════
TOOLS FOUND: 3
search_database → db.query (read, auto-approved)
send_email → email.send (write, requires approval)
delete_records → db.delete (delete, requires approval)
CLASSIFICATION: LLM-assisted (Claude)
CHANGES: written to agent.py
ACTION REQUIRED (1 item):
1. agent.py:42 — TODO(al-instrument): Replace tool references
in your agent constructor
NEXT STEPS:
1. Review the diff: git diff agent.py
2. Fix the TODO above (swap tool references)
3. Set AL_API_KEY in your environment
4. Run your agent — governance is active
5. Visit https://agentlattice.com/dashboard to configure policies
════════════════════════════════════════════════════
How It Fits Together
al-instrument generates code that uses two AgentLattice packages:
- agentlattice (Python SDK) provides the
AgentLatticeclient that communicates with the API - langchain-agentlattice provides the
govern()wrapper that gates tool execution
After instrumentation, every tool call flows through: Tool invoked → govern() calls al.gate() → AgentLattice evaluates policy → Approved/Denied → Tool executes or raises error.
Configure policies, approval flows, and audit rules in the AgentLattice dashboard.
Metadata
Release files for al-instrument 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 |
|---|---|---|---|---|
| al_instrument-0.1.1.tar.gz | 26.6 kB | Without provenance | Details for al_instrument-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| al_instrument-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for al_instrument-0.1.1-py3-none-any.whl |
Total release size: 46.9 kB
Release files / al_instrument-0.1.1.tar.gz
| Download URL | al_instrument-0.1.1.tar.gz |
|---|---|
| Size | 26.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc4c35b15bc77c4c3037ef325b47f1891d6b9156a10046cdcb06030eca80405d
|
|
BLAKE2b-256 checksum How to use checksums |
3f5ad739109aaf14b70b0c3a0c21991c1462cf0b3453f2ddbcd88512f74ba101
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / al_instrument-0.1.1-py3-none-any.whl
| Download URL | al_instrument-0.1.1-py3-none-any.whl |
|---|---|
| Size | 20.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a52c723c52537ebadb1f8f14457744d7183a7183b9a6a0dbd576c6c2f5b435f2
|
|
BLAKE2b-256 checksum How to use checksums |
7470804e98dc0dcfccae586491525a02fde9e791b8b31ab984e5d5c54120be1c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Security for al-instrument 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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.