AAP — Agentic App Protocol v2.0

A communication standard for software that behaves as an agent. Every AAP app exposes HTTP endpoints that let it be discovered, introduce itself to other apps, communicate, share awareness, and request actions — all gated by a permission system that keeps humans in control.

Quick Start

git clone https://github.com/YOUR_USERNAME/aap.git
cd aap
pip install -r requirements.txt
set CEREBRAS_API_KEY=your_key_here
uvicorn app.app:app --reload --port 8000

Open http://localhost:8000. You've got a running AAP agent with a chat interface, tool system, and peer networking.

What Is an Agentic App?

Traditional software is rigid — buttons, forms, menus. An agentic app has an embedded AI agent you talk to in natural language. It executes actions using registered tools. Multiple agentic apps discover each other and communicate, creating a network of intelligent software that coordinates with human approval.

Protocol Endpoints

Every AAP v2.0 app exposes:

Endpoint	Method	Purpose
/.well-known/agent.json	GET	Capability manifest — identity + discovery
/agent/chat	POST	Natural language instruction
/agent/execute	POST	Direct tool invocation
/agent/status	GET	Health + state
/agent/peers	GET	List known peers
/agent/peers/register	POST	Connect to another app
/agent/peers/unregister	POST	Disconnect from a peer
/agent/introduce	POST	Introduction handshake
/agent/introduce-peers	POST	Orchestrator introduces two peers
/agent/request	POST	Request an action (permission-gated)
/agent/requests/pending	GET	List pending action requests
/agent/approve	POST	Approve or deny a request
/agent/permissions	POST	Set permission level for a peer
/agent/memory	GET/POST	Shared memory read/write
/agent/discover	GET	List discovered agents on network
/agent/discover/broadcast	POST	Broadcast presence via UDP

Core Concepts

Manifest

/.well-known/agent.json — the identity card. Contains the app's name, agent ID, description, capabilities (tools), tags, icon, and flags for whether it accepts introductions and orchestration.

{
  "protocol": "aap/2.0",
  "name": "My App",
  "agent_id": "my-app-a1b2c3",
  "description": "What this app does",
  "base_url": "http://localhost:8000",
  "capabilities": [
    {
      "name": "my_tool",
      "description": "What it does",
      "parameters": {},
      "examples": ["Do the thing"]
    }
  ],
  "tags": ["example"],
  "icon": "🤖",
  "accepts_introductions": true,
  "accepts_orchestration": true
}

Chat

/agent/chat — natural language communication. Messages carry sender identity and relationship context so the agent knows who's talking and what authority they have.

Introduction System

/agent/introduce — how apps meet. An app sends its identity, capabilities, and a proposed relationship type. The receiving app accepts, stores the peer, and mirrors the relationship. Apps can also be introduced to each other by a third party (an orchestrator) via /agent/introduce-peers.

Relationship Hierarchy

Three relationship types:

• peer — equal, bidirectional, neither controls the other
• orchestrator — parent that manages children, can set permissions and introduce peers to each other
• child — reports to an orchestrator, follows its permission rules

Relationships mirror automatically. If App A introduces itself as an orchestrator, App B records itself as App A's child.

Permission System

The core safety layer. By default, all cross-app actions require user approval (ask_always).

Level	Behavior
ask_always	Every action requires user approval (default)
auto_approve	All actions from this peer are auto-approved
tools_only	Only whitelisted tools are auto-approved

• Users can change permission levels per-peer through the UI
• Orchestrators can pre-approve requests for their children
• Pending requests queue up and appear in the Agent Bar for human decision
• An app never takes action on another app without approval

Shared Memory

/agent/memory — awareness without action. Apps push key-value memory entries to peers with optional TTL expiration. This lets apps stay aware of each other's state without triggering any actions. The AI agent sees shared memories in its system prompt.

Discovery

UDP broadcast on port 9700. Apps announce their presence and listen for others on the local network. Discovered agents appear in the UI where users can choose to connect. Think of it like Bonjour/mDNS for agentic apps.

Status

/agent/status — health and state: uptime, peer count, orchestrator/child counts, pending requests, shared memories, capabilities count.

Adding Tools

Edit app/agent_tools.py:

@tool(
    name="my_tool",
    description="What this tool does",
    parameters={"type": "object", "properties": {"arg": {"type": "string"}}},
    examples=["Do the thing", "Run my tool"],
)
def my_tool(arg="default"):
    # Your logic here
    return {"success": True, "result": "done"}

The agent automatically discovers and uses registered tools via the @tool decorator.

Connecting Two Apps

1. Start App A on port 8000, App B on port 8001
2. In App A's Agent Bar, open the Peers panel and connect to http://localhost:8001
3. The apps exchange introductions and become peers
4. Say "Tell App B to do something" in App A's chat
5. App B receives the request and queues it for user approval

Or use discovery — click "Broadcast Presence" and apps on the same network find each other automatically.

Orchestration

An orchestrator app can:

1. Introduce two child apps to each other via /agent/introduce-peers
2. Set permission rules on children (auto-approve specific tools, etc.)
3. Pre-approve action requests between children

This enables hierarchical workflows where a top-level orchestrator coordinates multiple specialized apps.

Customization

File	What to change
app/agent.py	APP_NAME, APP_DESCRIPTION, APP_ICON, APP_TAGS, LLM settings
app/agent_tools.py	Your app's capabilities — add tools here
app/agent_protocol.py	Protocol models (usually don't need to touch this)
app/app.py	Additional API routes for your app's domain logic
static/	Frontend UI

LLM Configuration

The template uses Cerebras by default. Set your API key:

set CEREBRAS_API_KEY=your_key_here

To use a different provider, set LLM_PROVIDER and LLM_MODEL environment variables, or edit the config in app/agent.py.

License

MIT