Chat agent with a tool

An agent that answers questions about orders, and a plain Python function it calls to look one up. Six lines of declaration: no JSON schema, no call parsing, no tool loop. Source.

.agentdeck/
└── agents/order_desk/agent.py    # @tool + Agent(name="OrderDesk", tools=[...])
run.py                            # deck.run("OrderDesk", "where is order A-1001?")

The file's location is the registration. Nothing imports agent.py, and there is no catalog file to add it to.

The declaration

from agentdeck import Agent, tool

_ORDERS = {"A-1001": "shipped, arriving Thursday"}


@tool
def order_status(order_id: str) -> str:
    """Look up the current status of one order by its id."""
    return _ORDERS.get(order_id, "no such order")


order_desk = Agent(
    name="OrderDesk",
    instructions=(
        "You are the order desk for an online shop. Call order_status before answering any "
        "question about an order, and never guess a status. Keep replies to one short sentence."
    ),
    tools=[order_status],
)

Run it

uv pip install agentdeck-sdk
export OPENAI_MODEL=gpt-4.1-mini OPENAI_API_KEY=sk-...
python run.py

Run it from the example's own directory: Deck.from_project() discovers ./.agentdeck, so the working directory picks the project. OPENAI_BASE_URL points it at any OpenAI-compatible server instead, and Chat-Completions-only servers also want OPENAI_USE_RESPONSES=false.

What to look at

The parameter schema comes off the type hints and the description off the docstring; build() compiles the function into the tool the model is offered. A sync body runs on a worker thread rather than the event loop.
The instructions telling the model to call the tool are the whole contract. No rule engine enforces it.
The tool runs in this process with these privileges, on arguments the model chose. Keep anything destructive behind human approval rather than an agent's judgement.

Next: Tools · Agents