Skip to content

Quick Start#

Get up and running with OpenIntent in under a minute.

1. Start a Server#

pip install openintent[server]
openintent-server

from openintent.server import OpenIntentServer

server = OpenIntentServer(
    host="0.0.0.0",
    port=8000,
    database_url="sqlite:///openintent.db"
)
server.run()

Server is running

The server runs on http://localhost:8000. OpenAPI docs are at /docs.

2. Create Your First Intent#

from openintent import OpenIntentClient

client = OpenIntentClient(
    base_url="http://localhost:8000",
    agent_id="my-first-agent"
)

# Create an intent — the fundamental unit of coordination
intent = client.create_intent(
    title="Plan a trip to Paris",
    description="Research flights, hotels, and attractions"
)

print(f"Created: {intent.id}")
print(f"Status:  {intent.status}")   # "draft"
print(f"Version: {intent.version}")  # 1

3. Update State#

State is a flexible key-value store with optimistic concurrency:

updated = client.patch_state(
    intent.id,
    {
        "flights_researched": True,
        "hotels_found": 5,
        "budget_remaining": 2000
    }
)

print(f"Version: {updated.version}")  # 2 (auto-incremented)

Concurrency safety

State updates use optimistic concurrency control. If two agents try to update the same intent simultaneously, the second will get a 409 Conflict and can retry with the latest version.

4. Log Events#

Every action creates an auditable event:

from openintent.models import EventType

client.log_event(
    intent.id,
    EventType.STATE_PATCHED,
    payload={"step": "research", "progress": 0.5}
)

5. Complete the Intent#

completed = client.complete_intent(intent.id)
print(f"Status: {completed.status}")  # "completed"

The Full Picture#

sequenceDiagram
    participant A as Agent
    participant S as OpenIntent Server
    participant DB as Database

    A->>S: create_intent("Plan trip to Paris")
    S->>DB: Store intent (v1)
    S-->>A: Intent {id, status: "draft", version: 1}

    A->>S: patch_state(id, {flights: true})
    S->>DB: Update state (v1 → v2)
    S-->>A: Intent {version: 2}

    A->>S: log_event(id, STATE_PATCHED)
    S->>DB: Append to event log
    S-->>A: Event {seq: 1}

    A->>S: complete_intent(id)
    S->>DB: Update status (v2 → v3)
    S-->>A: Intent {status: "completed"}

Run the Demo#

Interactive demo

Try the built-in demo that showcases multi-agent coordination:

openintent demo

OPENAI_API_KEY=sk-... openintent demo

Next Steps#

Agent Abstractions

Build full agents with decorators, lifecycle hooks, memory, and tool access.

Build agents
YAML Workflows

Define multi-agent pipelines declaratively without writing code.

Write workflows
LLM Adapters

Add automatic observability to OpenAI, Anthropic, Gemini, and 4 more providers.

Add adapters