ADK Reference

Developer Reference

This page covers internal implementation details. It is not included in the User Guide.

CLI reference for the Escher ADK — Agent Development Kit. Source: v4-adk/README.MD and v4-adk/run.md.

Implementation status

The ADK is invoked as a Python module — python -m adk <subcommand>. The two subcommands implemented today are register and register-all, both with an optional --dry-run flag. Validation runs as part of register / register-all (a --dry-run flag returns validation results without writing to the Context Engine). The repo's GAPS.md documents fields and behaviour the implementation does not yet cover relative to the v4 architecture spec.

---

Local setup

From v4-adk/run.md. The ADK calls the Context Engine which calls the Asset Store; you need all three running.

# 1. (optional) Run SurrealDB locally — skip if your Asset Store .env points at a remote instance
surreal start --bind 0.0.0.0:4000 --user root --pass root memory

# 2. Asset Store (port 8000)
cd v4-asset-store-go
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
asset-store-migrate           # first time only
uvicorn asset_store.app:app --host 0.0.0.0 --port 8000 --reload

# 3. Context Engine (port 8001)
cd v4-context-engine
python3 -m venv myenv && source myenv/bin/activate
pip install -r requirements.txt
uvicorn context_engine.main:app --host 0.0.0.0 --port 8001 --reload

# 4. ADK
cd v4-adk
python3 -m venv adkenv && source adkenv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# .env: CE_URL=http://localhost:8001
#       PACKAGE_BASE_DIR=s3://escher-adk-packages/   (or local path like data/)

---

Commands

python -m adk register PATH [--dry-run]

Register a single agent package directory into the Context Engine.

# Dry run — validate against the schema and show what would be registered;
# no calls to the CE are made.
python -m adk register data/security_exposure_agent --dry-run

# Full registration — POSTs each asset to the CE which writes through Asset Store.
python -m adk register data/security_exposure_agent

The PATH is a directory containing an agent.yaml plus its supporting files (skills, playbooks, tools, context_builders).

---

python -m adk register-all [PATH] [--dry-run]

Register every agent package found under a directory (or under the configured S3 path if no PATH is given).

# All packages from S3 (uses PACKAGE_BASE_DIR from .env)
python -m adk register-all

# All packages from a local directory
python -m adk register-all data/

# Validate-only across all packages
python -m adk register-all data/ --dry-run

---

Environment variables

From v4-adk/.env.example:

Variable	Default	Description
CE_URL	http://localhost:8001	Context Engine base URL
PACKAGE_BASE_DIR	s3://escher-adk-packages/	Where register-all (no path) reads from

---

Working agent packages in the repo

The v4-adk repo ships four reference packages used by the team to test and seed the platform. Each is a directory containing an agent.yaml plus skills/tools/etc.:

• compliance-audit-agent/
• cost-query-agent/
• iam-security-agent/
• soc2-audit-agent/

The iam-security-agent/agent.yaml is the simplest fully-fleshed example — read that first when authoring a new package.

---

Implementation gaps (from v4-adk/GAPS.md)

Several v4 spec items aren't yet wired in code. Notable gaps the GAPS file calls out:

• tool_ids field on the skill manifest model (required by spec, missing from models.py)
• tenant_id on the agent manifest (spec requires explicit null; absent from model)
• Readonly tool-class allowlist enforcement (_READONLY_TOOL_CLASSES is dead code in the validator)
• Domain-specific readonly classes iam_read and audit_read not in the validator allowlist

Treat the spec at v4-architecture-docs/adk.md and agents.yaml.md as the target. The implementation will catch up; until then, expect spec/code drift.

---

Next steps

• agent.yaml Reference — Full schema spec + working iam-security-agent example
• Authoring Workflow — The 5-mode Authoring Agent for non-CLI users
• Context Engine API — What python -m adk register actually POSTs to