agentgate

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 9 Open GitHub ↗

Agent-native web protocol — expose your backend directly to AI agents, no HTML parsing required

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# agentgate

**The agent-native web protocol. Give AI agents a structured API instead of a website.**

---

When an AI agent visits `foodpanda.com` today, it downloads HTML meant for human eyes — navigation menus, ad banners, modals — and burns context window and compute trying to parse it into actions. `agentgate` fixes this at the source.

Website operators add `agentgate` to their FastAPI backend in an afternoon. From that point on, any AI agent that sends `X-Agent-Request: true` gets back a machine-readable manifest describing exactly what the site can do and how to do it — no HTML, no scraping, no prompt engineering around DOM structure.

```
Agent  ──→  GET /.well-known/agent-manifest.json  ──→  {intents, flows, schemas}
Agent  ──→  POST /agent/flows/order_food/start     ──→  {session_id, entry_step}
Agent  ──→  POST /agent/flows/order_food/step/...  ──→  {result, next_steps}
```

---

## Why not MCP?

[Model Context Protocol](https://modelcontextprotocol.io) (MCP) is excellent at what it does: connecting an LLM to **tools and resources in a local or operator-controlled environment** — file systems, databases, internal APIs, development tools. It is a client-side protocol designed to expand what a model can do inside a session.

`agentgate` solves a different problem: **any website on the public internet becoming natively callable by agents without prior integration work**.

| | MCP | agentgate |
|---|---|---|
| **Where it lives** | Sidecar process, stdio or SSE | Embedded in your existing web server |
| **Who configures it** | The LLM client / operator | The website operator |
| **Discovery** | Pre-configured — agent must know the server exists | Universal: `GET /.well-known/agent-manifest.json` on any domain |
| **Primary purpose** | Expand LLM tool access (files, DBs, APIs) | Make any website natively callable by agents |
| **Multi-step workflows** | Manual — agent orchestrates with raw tool calls | Built-in: `server` and `client` orchestration modes |
| **Session / state** | Not part of the protocol | First-class: server holds state across steps |
| **Transport** | stdio, SSE, HTTP (custom) | Standard HTTP — works with any `httpx`/`requests` client |
| **Existing website** | Requires separate MCP server process | `app.mount(fastapi_app)` — one line |
| **Agent compatibility** | Requires MCP-aware client | Any HTTP client; no framework required |
| **Open web scale** | Designed for closed, operator-controlled tools | Designed for the open web — discover any domain at runtime |

MCP and `agentgate` are **complementary, not competing**. An agent can use MCP to access its own tools (memory, code execution, calendar) while using `agentgate` to interact with external websites (e-commerce, booking, search).

---

## How it works

```
┌─────────────────────────────────────────────────────────────┐
│  Website (FastAPI)                                          │
│                                                             │
│   agentgate.mount()  ──adds──▶  /.well-known/agent-manifest │
│                                 /agent/intents/{name}        │
│                                 /agent/flows/{name}/start    │
│                                 /agent/flows/{name}/step/... │
│                                                             │
│   Normal routes are untouched — browsers see no change      │
└─────────────────────────────────────────────────────────────┘
         ▲
         │  X-Agent-Request: true
         │
┌─────────────────────┐
│  AI Agent           │
│                     │
│  client.discover()  │  ──▶  fetches manifest, understands capabilities
│  site.intents.*()   │  ──▶  one-shot structured calls
│  site.flows.*.start()──▶  starts stateful multi-step workflows
│  session.step(...)  │  ──▶  advances flow, server validates transitions
└─────────────────────┘
```

1. **Discover**: Agent fetches `/.well-known/agent-manifest.json`. The manifest lists every intent (single-step call) and flow (multi-step workflow) the site exposes, with full JSON Schema for inputs and outputs. No prior knowledge needed.
2. **Call intents**: Single-purpose actions (search, lookup, translate) — one request, one response.
3. **Execute flows**: Multi-step processes (order food, book a flight, register an account). Two modes:
   - **Server-orchestrated**: The server holds session state and enforces valid step transitions. The agent cannot skip steps or jump ahead — the server validates everything.
   - **Client-orchestrated**: Each step is an independent, stateless endpoint. The agent manages data chaining. Simpler for the server; suited for idempotent or read-heavy workflows.

---

## Installation

```bash
pip install agentgate
```

For running the development server:

```bash
pip install "agentgate[server]"   # includes uvicorn
```

**Requirements**: Python 3.10+, FastAPI, Pydantic v2, httpx

---

## Quick start — server side

Add `agentgate` to an existing FastAPI app in four steps.

### 1. Create an `AgentApp`

```python
from agentgate import AgentApp, AuthDef, step
from fastapi import FastAPI

agent_app = AgentApp(
    title="MyShop",
    description="E-commerce API for AI agents",
    version="1.0",
    auth=AuthDef(type="api_key", header="X-API-Key"),
)
```

### 2. Register intents (single-step capabilities)

Decorate any async function. Input and output schemas are auto-generated from type hints using Pydantic.

```python
from pydantic import BaseModel

class Product(BaseModel):
    id: str
    name: str
    price: float

@agent_app.intent("search_products", description="Search products by keyword")
async def search_products(query: str, max_results: int = 10) -> list[Product]:
    # your existing business logic
    return db.search(query, limit=max_results)
```

### 3. Register flows (multi-step workflows)

Use `@agent_app.flow` on a class and `@step` on its methods.

**Server-orchestrated** — the server holds session state and enforces step order:

```python
class CartItem(BaseModel):
    product_id: str
    quantity: int

class OrderConfirmation(BaseModel):
    order_id: str
    total: float
    eta_minutes: int

@agent_app.flow("checkout", orchestration="server", description="Add to cart and place order")
class CheckoutFlow:

@step(entry=True, description="Add a product to the cart")
    async def add_to_cart(self, product_id: str, quantity: int) -> dict:
        return {"cart_id": cart.create(product_id, quantity)}

@step(after="add_to_cart", description="Confirm and place the order")
    async def place_order(self, cart_id: str, address: str) -> OrderConfirmation:
        order = orders.create(cart_id, address)
        return OrderConfirmation(order_id=order.id, total=order.total, eta_minutes=30)
```

**Client-orchestrated** — each step is stateless and independent:

```python
@agent_app.flow("track_order", orchestration="client", description="Track an existing order")
class TrackOrderFlow:

@step(entry=True, description="Initiate tracking for an order")
    async def initiate(self, order_id: str) -> dict:
        return {"tracking_id": tracking.start(order_id)}

@step(after="initiate", description="Poll for current status")
    async def get_status(self, tracking_id: str) -> dict:
        return {"status": tracking.get(tracking_id)}
```

### 4. Mount onto your FastAPI app

```python
fastapi_app = FastAPI(title="MyShop")
agent_app.mount(fastapi_app, base_url="https://myshop.com")
```

That's it. Your existing routes are completely untouched. Agents that send `X-Agent-Request: true` get the agent API; regular browsers see nothing different.

**Start the server:**

```bash
uvicorn myapp:fastapi_app --reload
```

---

## Quick start — agent / client side

```python
import asyncio
from agentgate import AgentClient

async def main():
    client = AgentClient(
        agent_id="my-shopping-agent",
        api_key="sk-...",       # injected automatically based on manifest auth type
    )

# Discover capabilities at runtime — no prior knowledge of the API needed
    site = await client.discover("https://myshop.com")
    print(site)
    # <DiscoveredSite 'MyShop' intents=['search_products'] flows=['checkout', 'track_order']>

# Call a single intent
    products = await site.intents.search_products(query="wireless headphones", max_results=5)

# Execute a server-orchestrated flow
    session = await site.flows.checkout.start()
    cart = await session.step("add_to_cart", product_id=products[0]["id"], quantity=1)
    order = await session.step("place_order", cart_id=cart["cart_id"], address="Berlin, DE")
    print(order)          # {"order_id": "...", "total": 79.99, "eta_minutes": 30}
    print(session.is_complete)  # True

# Execute a client-orchestrated flow
    tracking = await site.flows.track_order.steps.initiate(order_id=order["order_id"])
    status = await site.flows.track_order.steps.get_status(tracking_id=tracking["tracking_id"])
    print(status)

asyncio.run(main())
```

---

## Full example — FoodPanda

The `examples/` directory contains a complete server + client pair:

```bash
# Terminal 1 — start the server
uvicorn examples.foodpanda_server:fastapi_app --reload

# Terminal 2 — run the agent
python examples/agent_client.py
```

[examples/foodpanda_server.py](examples/foodpanda_server.py) — FoodPanda-style backend with search intent, server-orchestrated ordering flow, and client-orchestrated tracking flow.

[examples/agent_client.py](examples/agent_client.py) — Agent that discovers, calls intents, and executes both flow types end-to-end.

---

## Core concepts

### The manifest

Every agentgate-enabled site serves `GET /.well-known/agent-manifest.json`. This is the contract between the site and any agent. The manifest is **auto-generated from your type annotations** — you don't write JSON Schema by hand.

```json
{
  "agent_api_version": "1.0",
  "name": "MyShop",
  "description": "E-commerce API for AI agents",
  "base_url": "https://myshop.com",
  "auth": {
    "type": "api_key",
    "header": "X-API-Key"
  },
  "intents": [
    {
      "name": "search_products",
      "description": "Search products by keyword",
      "endpoint": "/agent/intents/search_products",
      "method": "POST",
      "input_schema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "max_results": { "type": "integer" }
        },
        "required": ["query"]
      },
      "output_schema": { ... }
    }
  ],
  "flows": [
    {
      "name": "checkout",
      "orchestration": "server",
      "steps": [
        {
          "name": "add_to_cart",
          "entry": true,
          "next_steps": ["place_order"],
          "input_schema": { ... },
          "output_schema": { ... }
        },
        {
          "name": "place_order",
          "entry": false,
          "next_steps": [],
          "input_schema": { ... },
          "output_schema": { ... }
        }
      ]
    }
  ]
}
```

### Intents

An intent is a single-step, stateless capability. Use intents for lookups, searches, calculations — anything that takes inputs and returns a result in one call.

```python
@agent_app.intent("convert_currency", description="Convert between currencies")
async def convert_currency(amount: float, from_currency: str, to_currency: str) -> dict:
    rate = fx.get_rate(from_currency, to_currency)
    return {"converted": amount * rate, "rate": rate}
```

Agents call it as:
```
POST /agent/intents/convert_currency
{"amount": 100, "from_currency": "USD", "to_currency": "EUR"}
```

### Flows

A flow is a named, ordered sequence of steps. Use flows for multi-step business processes — booking, ordering, registration, configuration wizards.

Each `@step` decorator links steps by name:
- `entry=True` — this is the first step agents must call
- `after="step_name"` — this step becomes available after `step_name` completes

**Choosing between server and client orchestration:**

| | Server-orchestrated | Client-orchestrated |
|---|---|---|
| State lives in | Server session store | Agent / caller |
| Step enforcement | Server validates transitions | Agent responsible |
| Best for | Orders, payments, multi-stage forms | Status polling, idempotent reads |
| Session header | `X-Session-ID` required | Not needed |

### Authentication

Set auth policy on `AgentApp`. The client SDK injects credentials automatically based on what the manifest declares.

```python
# API key (injected as X-API-Key header)
auth=AuthDef(type="api_key", header="X-API-Key")

# Bearer token (injected as Authorization: Bearer ...)
auth=AuthDef(type="bearer")

# No auth required
auth=AuthDef(type="none")
```

On the client:
```python
client = AgentClient(agent_id="my-agent", api_key="sk-...")
# api_key is injected automatically based on what the manifest says
```

### Custom session store

The default `MemorySessionStore` is suitable for development. In production, implement the `SessionStore` protocol to back sessions with Redis, a database, or any other store.

```python
from agentgate.server.session import SessionStore, FlowSession

class RedisSessionStore:
    async def create(self, flow_name: str, entry_step: str, allowed_next: list[str]) -> FlowSession: ...
    async def get(self, session_id: str) -> FlowSession: ...
    async def update(self, session: FlowSession) -> None: ...

agent_app = AgentApp(
    title="MyShop",
    session_store=RedisSessionStore(),
)
```

---

## HTTP protocol reference

### Agent identification headers

Sent by the client on every request:

| Header | Value | Required |
|---|---|---|
| `X-Agent-Request` | `true` | Yes |
| `X-Agent-ID` | Any string identifier for the agent | No |
| `X-Agent-Version` | `1.0` | No |

### Endpoints

| Method | Path | Description |
|---|---|---|
| `GET` | `/.well-known/agent-manifest.json` | Discover capabilities |
| `POST` | `/agent/intents/{name}` | Execute an intent |
| `POST` | `/agent/flows/{name}/start` | Start a server-orchestrated flow session |
| `POST` | `/agent/flows/{name}/step/{step_name}` | Advance a server-orchestrated step (requires `X-Session-ID`) |
| `GET` | `/agent/flows/{name}/session/{session_id}` | Inspect a server-orchestrated session |
| `POST` | `/agent/flows/{name}/steps/{step_name}` | Execute a client-orchestrated step (stateless) |

### Flow start response

```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "entry_step": "add_to_cart",
  "allowed_next_steps": ["add_to_cart"],
  "input_schema": { ... }
}
```

### Step response

```json
{
  "result": { ... },
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "current_step": "add_to_cart",
  "allowed_next_steps": ["place_order"],
  "flow_complete": false
}
```

### Error response

All errors follow a standard shape:

```json
{
  "error": "step_not_allowed",
  "message": "Step 'place_order' cannot follow ''. Allowed next: ['add_to_cart']",
  "current_step": "",
  "allowed_next_steps": ["add_to_cart"]
}
```

| HTTP status | Meaning |
|---|---|
| `400` | Missing required header (e.g. `X-Session-ID`) |
| `401` | Authentication failed |
| `404` | Intent, flow, or session not found |
| `422` | Invalid step transition or bad input |

---

## Error handling — client side

```python
from agentgate import (
    ManifestNotFoundError,   # site does not support agentgate
    StepTransitionError,     # tried to skip a step
    SessionNotFoundError,    # session expired or invalid
    IntentError,             # intent execution failed
    FlowNotFoundError,       # flow name not in manifest
)

try:
    site = await client.discover("https://example.com")
except ManifestNotFoundError:
    print("This site does not support agentgate")

try:
    await session.step("place_order", ...)
except StepTransitionError as e:
    print(f"Can't go there yet. Allowed: {e.allowed}")
```

---

## Package structure

```
agentgate/
├── shared/
│   ├── manifest.py      # Pydantic models: Manifest, IntentDef, FlowDef, StepDef, AuthDef
│   ├── protocol.py      # Protocol constants: headers, paths, version
│   └── errors.py        # Exception hierarchy
├── server/
│   ├── app.py           # AgentApp — main entry point for website operators
│   ├── decorators.py    # @app.intent, @app.flow, @step
│   ├── manifest.py      # Auto-generation from type hints via Pydantic + inspect
│   ├── router.py        # FastAPI APIRouter wiring all agent endpoints
│   ├── middleware.py    # AgentDetectionMiddleware
│   └── session.py       # FlowSession dataclass, SessionStore protocol, MemorySessionStore
└── client/
    ├── client.py        # AgentClient — main entry point for AI agents
    ├── discovery.py     # Manifest fetching + TTL cache
    ├── site.py          # DiscoveredSite with .intents and .flows dynamic namespaces
    └── executor.py      # IntentExecutor, ServerFlowSession, ClientFlowStepProxy
```

---

## Roadmap

- [ ] Django and Starlette adapters
- [ ] OAuth2 and JWT built-in auth support
- [ ] Streaming step responses (Server-Sent Events)
- [ ] Manifest versioning and changelog
- [ ] Official `agentgate.json` registry — a public directory of agent-native sites
- [ ] OpenAPI → agentgate manifest migration tool

---

## Running the tests

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
```

---

## License

MIT

agentgate

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README