Skip to content

Quickstart

This is the canonical first application path. You need Python 3.11+ and uv. The first verification stage runs without credentials; a live model run uses your chosen provider.

Create and verify

Section titled “Create and verify”
Terminal window
uvx cayu new myagent
cd myagent
uv sync --extra dev
uv run --no-sync cayu guide anatomy
uv run --no-sync cayu inspect --json
uv run --no-sync cayu check --fail-on warning --json
uv run --no-sync pytest
uv run --no-sync cayu eval run

Inspection should identify the registered agent and configured stores. The strict check should exit successfully with no warning-or-higher diagnostics. The generated tests and eval inject a deterministic provider through the application’s public factory seam. Passing them proves the starter’s runtime behavior; live-model quality is evaluated separately.

Read the project

Section titled “Read the project”
File or directory Responsibility
pyproject.toml Declares [tool.cayu] factory = "app:build_app" and dependencies
app.py Constructs and registers one fresh process-local application
configuration/ Settings, providers and storage
agents/ and prompts/ Agent identity and model-facing instructions
tools/ Domain tools and their registration
tests/ and evals/ Behavioral checks
run.py The application-owned first-run entrypoint
AGENTS.md Local placement and verification rules for coding agents

Keep app.py focused on construction and registration. Put business calculations in their owning modules. Read application anatomy for process roles and cleanup.

Give the first agent a job

Section titled “Give the first agent a job”

Edit the existing agent and prompt rather than retaining the starter and adding a second agent. For example: accept a support request, identify missing order information, and return an evidence-based summary. Update the existing test and eval to express the required behavior.

A model-only job needs no tools. Add a tool when the agent needs an application capability, such as reading an order or preparing a proposal. Follow tool authoring when that requirement appears.

Configure a provider and run

Section titled “Configure a provider and run”

Choose a supported provider and model in configuration/settings.py or through the generated CAYU_PROVIDER setting. Set the credentials specified in the provider guide. Then:

Terminal window
uv run --no-sync python run.py --message "Summarize this support request: my order arrived damaged."

Inspect the emitted events and final outcome. A provider authentication failure is a configuration problem; a session that fails or pauses is a runtime outcome that requires its recorded evidence.

Open the local dashboard

Section titled “Open the local dashboard”
Terminal window
uv run --no-sync cayu serve --dev --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000/cayu/. The explicit local development profile is for trusted loopback access. Read server setup before deploying.

Continue

Section titled “Continue”

Re-run inspect, the strict check, tests and eval after changing behavior. Try the restartable support recipe for a complete credential-free journey through clarification, approval, execution and independent verification. Look up exact arguments in the Python API.