Agents

Curate-Me runs AI work in two ways: Autopilot templates (managed, recurring jobs you assign from the dashboard or API) and SDK-managed agents (agents you register and run programmatically through the curate-me SDK). This page covers both, plus how runs stream events and how cost is tracked.

Note: Agents do not run an in-process “framework” inside your app. They execute server-side — Autopilot templates run in managed runners, and SDK agents are dispatched through the platform API. Your application calls the API/SDK; governance, cost recording, and observability are applied by the platform, not by a base class you subclass.

Running an agent with the SDK

The curate-me SDK exposes a client.agents sub-client. An agent is referenced by an opaque agent_id — you create or look one up, then run it with input.


from curate_me import CurateMe
 
client = CurateMe(api_key="cm_sk_...", org_id="org_123")
# Or: client = CurateMe.from_env()
 
# Run an existing agent by id
run = await client.agents.run(
    "agt_123",
    input={"query": "Summarize the latest incident report"},
)
print(run.status, run.output)

Every method also has a *_sync variant for non-async callers (e.g. client.agents.run_sync(...)).

Agent lifecycle methods

client.agents covers the full lifecycle:

Method	Purpose
`list(status=..., limit=..., offset=...)`	List agents, optionally filtered by status
`get(agent_id)`	Fetch a single agent
`create(name=..., model=..., description=..., config=...)`	Register a new agent
`update(agent_id, ...)`	Update an agent’s name, model, status, or config
`delete(agent_id)`	Delete an agent
`run(agent_id, input=...)`	Execute the agent and wait for the result (`AgentRun`)
`stream(agent_id, input=...)`	Execute and stream `StreamEvent`s as they occur
`get_run(agent_id, run_id)`	Fetch a past run
`list_runs(agent_id, ...)`	List runs for an agent
`cancel_run(agent_id, run_id)`	Cancel an in-flight run

Creating an agent takes a model identifier — use a current production model, for example claude-sonnet-4-6, claude-opus-4-7, claude-haiku-4-5-20251001, or a gpt-4o family model:


agent = await client.agents.create(
    name="incident-summarizer",
    model="claude-sonnet-4-6",
    description="Summarizes incident reports into an exec-ready brief",
)
run = await client.agents.run(agent.id, input={"report_id": "inc_998"})

Streaming run events

client.agents.stream(...) yields typed StreamEvent objects. Each event has a type (an EventType) and a data payload, so you can render progress without waiting for the full run:


async for event in client.agents.stream("agt_123", input={"query": "..."}):
    if event.type == "token":
        print(event.data.get("content", ""), end="")
    elif event.type == "agent_complete":
        print("\nDone:", event.data)

The EventType discriminators emitted by the SDK include:

Event type	Purpose
`agent_start`	Agent has begun execution
`agent_progress`	Incremental progress update
`token`	Incremental token from a streaming LLM response
`agent_complete`	Agent finished with a result
`agent_error`	Agent encountered an error
`tool_call` / `tool_result`	A tool was invoked and returned
`guardrail_check` / `guardrail_violation`	A guardrail ran (and, optionally, blocked)

Decorating your own functions

For agents whose logic lives in your own code, the SDK ships @agent and @trace decorators. They add tracing and run records around a plain function — they do not require any base class:


from curate_me import agent, trace
 
@agent(name="summarizer", model="claude-sonnet-4-6", tags=["analysis"])
async def summarize_text(input: dict) -> dict:
    text = input["text"]
    # ... your summarization logic, e.g. via the gateway proxy ...
    return {"summary": "..."}
 
@trace(name="enrich")
async def enrich(payload: dict) -> dict:
    return {"enriched": True, **payload}

Autopilot templates

Recurring, managed AI work is defined by Autopilot templates — the successor to the platform’s earlier in-repo agent framework. A template is a skill described by a SKILL.md contract and registered in the template registry; the dashboard, API, and Teams/Slack triggers all dispatch templated runs into managed runners.

Templates live at services/backend/src/services/autopilot/templates/skills/<name>/SKILL.md, are registered via register_template() / get_template() in services/backend/src/services/autopilot/registry.py, and each ships a docs page under docs/00-platform/autopilot-templates/<name>.md.

Built-in templates include:

Template	What it does
`dev_team`	Multi-role development workflow
`cfo`	Financial analysis and reporting
`security_audit`	Security review of a target
`code_review`	Automated PR / diff review
`customer_support`	Drafts support responses
`sales_research` / `product_research`	Account and product research
`news_digest` / `autoresearch`	Periodic research digests
`doc_drift`	Detects documentation drift
`pr_writer` / `repo_manager`	Repository and PR maintenance
`webwright_agent`	Browser agent (preview, behind `WEBWRIGHT_PREVIEW`)

See the full list and contract in AUTOPILOT_TEMPLATE_CONTRACT.md and the per-template pages under docs/00-platform/autopilot-templates/.

Adding a template

Create services/backend/src/services/autopilot/templates/skills/<your_skill>/SKILL.md with frontmatter (name, description, inputs, outputs).
Add services/backend/src/services/autopilot/templates/<your_skill>.py implementing the template entrypoint and calling register_template().
Import it from services/backend/src/services/autopilot/__init__.py so it lands in the registry at import time.
Add tests under tests/services/autopilot/.

Cost per request

LLM costs are recorded automatically by the gateway, per call and aggregated per agent and per org. Actual costs depend on the models selected, prompt length, and response length. The gateway governance chain enforces per-request cost limits and per-org daily budgets to prevent runaway spend.

Cost data is available through:

SDK: client.costs — e.g. await client.costs.get_summary(...), client.costs.get_by_agent(...), client.costs.get_by_model(...), and budget management (list_budgets / create_budget / check_budget)
Dashboard: Cost Governance panel with per-agent and per-org breakdowns
API: /api/v1/admin/costs endpoints for programmatic access
CLI: curate costs summary for command-line cost reports
Health endpoint: /api/v1/health reports daily spend totals