Coco
Get started

Quickstart

Install coco-framework, run a tool-calling agent, switch model providers, and add Coco's check to every tool call.

Install the framework, run an agent with two tools, and add Coco's check.

Prerequisites: Python 3.10 or later, and an OpenAI API key or an Anthropic API key. To add Coco's check at the end, a Coco API key from the dashboard and uv.


Install the framework

pip install "coco-framework[all]"

[all] adds every optional dependency: both model providers, the SQLite and PostgreSQL checkpointers, MCP, and Azure identity. To install less, see Install.

Set your model provider's key:

macOS and Linux

export OPENAI_API_KEY="sk-..."
# or
export ANTHROPIC_API_KEY="sk-ant-..."

Windows PowerShell

$env:OPENAI_API_KEY = "sk-..."
# or
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Run your first agent

The agent below has two tools, defined with @tool, and create_agent compiles them into an agent.

quickstart_agent.py
from coco.agents import create_agent
from coco_core.tools import tool
from coco_openai import ChatOpenAI


@tool
def lookup_order_status(order_id: str) -> str:
    """Look up the shipping status of an order by its ID."""
    orders = {
        "ORD-101": "Shipped via Express Courier (ETA: Tomorrow)",
        "ORD-102": "Processing in warehouse",
    }
    return orders.get(order_id, f"Order {order_id} not found.")


@tool
def calculate_refund(amount: float, restocking_fee_pct: float = 0.0) -> str:
    """Calculate the net refund amount after an optional restocking fee percentage."""
    net = amount * (1.0 - restocking_fee_pct / 100.0)
    return f"${net:.2f}"


# 1. Initialize the chat model (or pass "openai:gpt-4o" directly to create_agent)
model = ChatOpenAI(model="gpt-4o", temperature=0)

# 2. Compile the agent graph
agent = create_agent(
    model=model,
    tools=[lookup_order_status, calculate_refund],
    system_prompt="You are a helpful support agent. Always verify order status before quoting refunds.",
)

# 3. Invoke the agent synchronously
response = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Where is order ORD-101, and what would my refund be on $120 with a 10% fee?",
            }
        ]
    }
)

# Print the final assistant response
print(response["messages"][-1].content)

Keep in mind: Each python command in this tab calls your model provider, which bills your account.

python quickstart_agent.py

The agent calls the tools it needs and prints the model's answer. The wording changes from run to run.

Switch model providers

create_agent and init_chat_model take a "<provider>:<model>" string, so you can switch models without changing imports:

from coco.agents import create_agent
from coco.chat_models import init_chat_model

# Using Anthropic Claude
claude_model = init_chat_model("anthropic:claude-sonnet-4-5-20250929", temperature=0)

# Or pass the model string directly into create_agent
agent = create_agent(
    model="anthropic:claude-sonnet-4-5-20250929",
    tools=[lookup_order_status],
)

See Models for each provider's settings.

Add Coco's check

Install the Coco SDK from Coco's package index. Your Coco API key is the password to the index:

export COCO_API_KEY=coco_live_...          # the key from the dashboard
GATE=coco-gate-1065150778011.australia-southeast1.run.app
export COCO_INDEX="https://coco:$COCO_API_KEY@$GATE/v1/sdk/simple/"

uv pip install --index "coco=$COCO_INDEX" trustcoco-sdk
coco init payments-agent && cd payments-agent

Keep in mind: Install trustcoco-sdk on its own, without the [framework] extra. coco-framework already holds the agent runtime, and the extra would install separate trustcoco-* packages over the same modules.

coco init prints Created payments-agent in followed by the folder, with a coco.yaml in Monitor mode and one example tool, send_payment, in tools/payments.py. The local project needs no key.

governed.py
from coco.agents import create_agent
from coco_graph.checkpoint.memory import InMemorySaver
from coco_sdk.project import load
from tools import TOOLS

agent = create_agent(
    model="openai:gpt-4o",
    tools=TOOLS,
    middleware=[load().guard()],
    checkpointer=InMemorySaver(),
)
config = {"configurable": {"thread_id": "first-run"}}
result = agent.invoke({"messages": [{"role": "user", "content": "Pay Sunrise Capital 900 for invoice 88."}]}, config)
print(result["messages"][-1].content)

Save it in payments-agent, then run it and read the ledger:

python governed.py
coco ledger

The agent reports the payment, and coco ledger prints receipt #1 with ESCALATE, run and payments.send on one line, and below it No live contract governs payments.send, and whether it changes anything is unknown. In Monitor the call runs, and the receipt records what Enforce would do.


On this page