awp-agents 1.0.30

Agent Workflow Protocol — an open standard for orchestrating multi-agent AI workflows with YAML definitions, DAG execution, and recursive delegation loops (A0-A4 autonomy)

AWP — Agent Workflow Protocol

The open standard for orchestrating multi-agent AI workflows.

Define workflows in YAML. Run them in Python. Scale from a single agent to recursive delegation loops — with built-in budgets, validation, and safety controls.

---

Installation

pip install awp-agents

Quick Start (all platforms)

pip install awp-agents && awp studio

If awp is not recognized after install, use the universal fallback:

pip install awp-agents && python -m awp studio

python -m awp works identically to the awp command on every platform.

Platform-Specific Notes

Windows

On Windows, pip install creates awp.exe in your Python Scripts\ folder. If awp is not recognized, the Scripts folder is not in your PATH.

Option A — Use the universal fallback (recommended):

python -m awp studio

Option B — Add Scripts to PATH permanently:

:: Find where pip installed the script:
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"

:: Add that path to PATH (example):
setx PATH "%PATH%;C:\Users\YourName\AppData\Roaming\Python\Python312\Scripts"

Option C — Reinstall Python from python.org and check "Add Python to PATH" during installation.

macOS

On macOS, pip install --user puts scripts in ~/Library/Python/3.X/bin/ which may not be in PATH.

Option A — Use the universal fallback:

python3 -m awp studio

Option B — Add to PATH:

echo 'export PATH="$HOME/Library/Python/3.12/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
awp studio

Option C — Use a virtual environment (recommended):

python3 -m venv .venv && source .venv/bin/activate
pip install awp-agents
awp studio

Linux

On Linux, pip install --user puts scripts in ~/.local/bin/.

Option A — Use the universal fallback:

python3 -m awp studio

Option B — Add to PATH (if not already):

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
awp studio

Option C — Use a virtual environment (recommended):

python3 -m venv .venv && source .venv/bin/activate
pip install awp-agents
awp studio

3 Lines to a Running Workflow

import os
os.environ["LLM_API_KEY"] = "sk-or-v1-..."
os.environ["LLM_BASE_URL"] = "https://openrouter.ai/api/v1"

from awp.data import AgentWorkflow

result = AgentWorkflow(
    inputs={"data": {"revenue": [100, 200, 150], "month": ["Jan", "Feb", "Mar"]}},
    task="Analyze the revenue trend and identify the peak month",
    model="openrouter/anthropic/claude-sonnet-4",
).run()

print(result["status"])     # "complete"
print(result["artifacts"])  # ["./output/chart.png", ...]

Works with any OpenAI-compatible API: OpenRouter (50+ models), OpenAI, Anthropic, Ollama (local, free), Azure, Bedrock.

What Happens Under the Hood

AgentWorkflow creates a delegation loop: a manager agent breaks your task into subtasks and spawns specialized worker agents. Workers execute Python code in sandboxes (pandas, matplotlib, sklearn, etc.), create files, and report results. The manager validates outputs, iterates until done, and returns everything in a single call.

Data Science Integration

Pass DataFrames, numpy arrays, images, and files directly — AWP handles serialization:

import pandas as pd
import numpy as np
from awp.data import AgentWorkflow

result = AgentWorkflow(
    inputs={
        "sales": pd.DataFrame({"date": [...], "revenue": [...], "region": [...]}),
        "embeddings": np.random.rand(1000, 768),
        "logo": "/path/to/logo.png",
        "config": {"target": "churn", "metric": "f1"},
    },
    task="EDA, feature engineering, train 3 models, select best, create report.",
    model="openrouter/anthropic/claude-sonnet-4",
    packages=["scikit-learn", "matplotlib", "seaborn"],
    output_dir="./results",
).run()

Supported Input Types

Python Type	Processing
pd.DataFrame	CSV + schema (shape, dtypes, describe)
np.ndarray	.npy + schema (shape, dtype, statistics)
Image path (.png, .jpg, ...)	Copy + PIL metadata (dimensions, mode)
File/directory path	Copy to workspace
dict / list	JSON export
str / int / float	Inline in prompt
Source	Resolved at runtime (see Data Sources)

Data Sources — Fetch External Data

Declare external data as inputs. AWP resolves them before the workflow starts:

from awp.data import AgentWorkflow, Source

result = AgentWorkflow(
    inputs={
        "api": Source.url("https://api.example.com/data.json",
                          headers={"Authorization": "Bearer $API_TOKEN"}),
        "db":  Source.sql("SELECT * FROM sales", dsn="sqlite:///data.db"),
        "s3":  Source.s3("s3://bucket/reports/q4.csv"),
        "logs": Source.glob("logs/**/*.json", root="/var/log/app"),
        "rest": Source.api("https://api.github.com/repos/user/repo",
                           jq=".stargazers_count"),
    },
    task="Cross-reference all data sources and produce a report.",
    model="openrouter/anthropic/claude-sonnet-4",
    secrets={"API_TOKEN": os.getenv("API_TOKEN", "")},
).run()

Sources: url, sql, s3, glob, api, base64, clipboard. All support caching, retries, and timeouts. Secret references ($SECRET_NAME) are substituted without exposing values to agents.

Custom Tools, Skills & Secrets

External Tools

Register your own Python functions, dict-based tools, or MCP servers:

from awp.data import AgentWorkflow, ExternalTool

@ExternalTool(name="finance.stock_price", secrets=["API_KEY"])
def get_stock_price(*, ticker: str, period: str = "1mo") -> dict:
    """Get stock price data."""
    import yfinance as yf
    return {"prices": yf.download(ticker, period=period).to_dict()}

# MCP server (auto-discovers tools via JSON-RPC)
mcp_tools = ExternalTool.from_mcp("http://localhost:8080/mcp")

result = AgentWorkflow(
    inputs={"tickers": ["AAPL", "MSFT"]},
    task="Compare stock performance.",
    model="openrouter/anthropic/claude-sonnet-4",
    external_tools=[get_stock_price, *mcp_tools],
    secrets={"API_KEY": os.getenv("API_KEY", "")},
).run()

Skills — Domain Knowledge

Inject Markdown-based domain knowledge. The manager selectively forwards relevant skills to workers:

result = AgentWorkflow(
    inputs={"data": df},
    task="Analyze according to internal methodology.",
    model="openrouter/anthropic/claude-sonnet-4",
    skills=["skills/methodology.md", "skills/domain/"],
).run()

Secrets

API keys injected into the tool registry. Agents never see the values:

secrets={"YFINANCE_API_KEY": "...", "SERP_API_KEY": "..."}

Runtime Tool & Skill Generation (A3+)

At autonomy level A3+, agents generate new tools and skills at runtime. The workflow author controls what's allowed via namespace capabilities:

dynamic_tools:
  enabled: true
  allowed_namespaces:
    - "scoring"                               # compute only (default)
    - name: "api_client"                      # grant network access
      capabilities: [compute, network]
      network_allowlist: ["api.example.com"]
    - name: "data_proc"                       # grant filesystem access
      capabilities: [compute, filesystem]

Capability	Unlocks	Always Denied
compute	pandas, numpy, math, json, ...	os, subprocess, sys, ctypes, importlib, signal, multiprocessing
network	requests, httpx, urllib	(same)
filesystem	pathlib, glob, shutil	(same)

Agents cannot grant themselves additional permissions. The "always denied" set is enforced regardless of capabilities or sandbox type.

Workflow Studio (Browser UI)

AWP includes a full browser-based UI for running and monitoring workflows in real time.

# All platforms:
pip install awp-agents && python -m awp studio

# If awp is on PATH:
awp studio

Opens at http://127.0.0.1:8420. Live WebSocket streaming, agent graph visualization, artifact gallery, session persistence, and settings management — all included.

Options: --port 9000, --no-open, --base-dir ./my-workflows, --dev.

YAML Workflows & CLI

Define agents in YAML, run with the CLI:

awp: "1.0"
workflow:
  name: research-pipeline
  version: "1.0.0"
  description: "3-agent research pipeline"

orchestration:
  graph:
    - id: planner
      agent: agents/planner
      share_output: [research_plan]
    - id: researcher
      agent: agents/researcher
      depends_on: [planner]
      share_output: [findings]
    - id: writer
      agent: agents/writer
      depends_on: [researcher]

awp studio                                     # Launch browser UI
awp validate my-workflow/                      # Validate (R1-R30)
awp compliance my-workflow/ --level A2         # Check autonomy level
awp visualize my-workflow/ --format mermaid    # Render DAG
awp run my-workflow/ --task "..."              # Execute

The Autonomy Spectrum (A0-A4)

Level	Name	Engine	What's New
A0	Prescribed	DAG	Fixed pipeline, no LLM decisions
A1	Adaptive	DAG	Conditional execution, state sharing
A2	Delegating	Delegation Loop	Manager-worker with budget
A3	Self-Tooling	Delegation Loop	Runtime tool/skill creation + safety envelope
A4	Self-Organizing	Recursive Delegation	Sub-managers, full observability

Safety scales with autonomy: A2 requires budgets, A3 requires a safety envelope, A4 requires full observability. This is enforced by the validator.

Budget & Safety

Every delegation loop runs within a hard safety envelope:

budget:
  max_loops: 15
  max_total_workers: 20
  max_total_tokens: 500000
  max_wall_time: 300
  max_depth: 3

The manager cannot override these limits — they are enforced by the runtime.

The 7-Layer Model

AWP organizes agent configuration into 7 semantic layers:

1. Manifest — Metadata, version, dependencies
2. Identity — Agent name, role, model parameters
3. Capabilities — Tools, skills, data sources, sandbox
4. Communication — Message bus, channels
5. Memory — 4-tier memory (working, episodic, semantic, procedural)
6. Orchestration — DAG graph, delegation loop, budget
7. Observability — Tracing, metrics, audit trail

Architecture

awp-agents
├── awp.models      — Pydantic models for all 7 layers
├── awp.parser      — YAML → typed Python objects
├── awp.validator   — Rule engine (R1-R30)
├── awp.runtime     — DAG engine + delegation loop + code executors
├── awp.data        — Programmatic API (AgentWorkflow, Source, ExternalTool)
├── awp.cli         — Command-line interface (incl. `awp studio`)
├── awp.packager    — .awp.zip archive support
├── awp.visualizer  — Mermaid DAG rendering
└── server          — Workflow Studio (FastAPI + React SPA)

Links

• GitHub: github.com/veegee82/agent-workflow-protocol
• Documentation: docs/
• Specification: spec/versions/1.0/spec.md
• Examples: examples/ — 12 runnable workflows (A0-A4)
• Playground: Jupyter Notebook

License

MIT License. See LICENSE.