Build and publish
- Write a Python
Agentwithmanifest(),execute(spec, emit, ctx), andfinalize(spec)if it proposes changes. Declare the tables it reads or writes and any external host it contacts.emit.proposal(...)pauses the task for review and stores a checkpoint, by default the proposed content, whichfinalizereads asspec.ctx.resume_state. Passresume_state=to checkpoint something else. A proposal with an empty checkpoint is refused. - Save
manifest().json()asmanifest.jsonnext toagent.py. The SDK produces stable bytes so you can check the published declaration against the source. - Install
grpcioandprotobufinto the Python environment that runspython3, for example withpython3 -m pip install 'grpcio>=1.71,<2' 'protobuf>=5.29,<6'. Run the SDK’s conformance harness, thendip agent dev --prompt "hello"to exercise one local turn against the agent runtime. The local turn uses the manifest’stimeoutMinbudget. Omit the prompt to leave the runtime serving for manual calls. For a live local SQL or egress turn, supplyALTIMATE_AGENT_DEV_TOKENand the corresponding--trinoproxy-urlor--egress-proxy-url; the default local token is only a placeholder. - Run
dip agent build, thendip agent push. Publishing needsapps:publishfor the image andagents:publishfor the agent catalog. Dippr registers the pushed image by its digest. To publish another version under the same agent ID, increase the manifest version and rundip agent pushagain; the catalog is updated throughUpdateAgent.
dip agent build and dip agent push build it on a Python 3.12 base image with the SDK bundled in dip, install the optional requirements.txt beside agent.py (list anything the agent imports beyond the SDK, such as the packages of the OpenAI or Claude adapters), copy the directory to /opt/agent, and run python agent.py. They write nothing into your directory. dip agent push --platform linux/amd64 builds one architecture instead of both, which is much faster on a dev stack; an image built for one architecture runs only on nodes of that architecture.
If you bring your own Dockerfile (or agent.Dockerfile), your directory is its Docker build context and the Dockerfile must install the SDK itself. A Dockerfile copied from the repository’s warehouse-janitor or data-analyst example copies paths that exist only in this repository, so dip refuses it and tells you to delete it. Run the shipped examples with dip agent build --dir agents/examples/<name> from a repository checkout.
The warehouse-janitor example’s reviewed write inserts into lakehouse.sales.agent_review_probe, and nothing creates that table. Before the first approval, create it as a user allowed to create tables in lakehouse.sales:
FAILED while it applies the write.
When agent code raises an exception, the task ends FAILED and records an error with a plain message. To tell the person who ran the task what to fix, raise altimate_agent.AgentFailure("what failed and what to do next", code="MODEL_NOT_CONFIGURED"); its message and code reach the task as written (300 characters at most), so keep secrets and request content out of it. Any other exception reaches the task as a generic message naming only the exception class and pointing to the agent’s logs. The full traceback stays in the agent’s own log. The data-analyst example raises AgentFailure when its model key or token prices are missing, when the task has no egress proxy, or when the model provider answers with an error status.
The SDK’s run_sql, list_tables, and describe_table tools use a token issued for each task turn. Give the agent no separate database credentials. For agents you publish, model access uses a declared external host and a key supplied to the image. The built-in routine runner uses a model connection managed by your deployment; its model host is not an editable consent capability.
If you use run_agent with the OpenAI Agents SDK, pass cost_microusd= a function that prices its reported Usage object in integer millionths of a US dollar. For run_claude_agent, pass cost_microusd= a function accepting (model, usage) and returning the same integer unit. The Claude adapter uses the provider’s total cost when a result arrives, and your function prices usage already observed if the iterator fails before that result. An adapter refuses to complete when accounting is missing or invalid. Keep pricing current for every model your agent can select.
The default OpenAI and Claude adapters route provider requests through the authenticated egress proxy for that turn. OpenAI agents must use string model names so the adapter can install its per-run provider; the Claude adapter disables the Claude CLI’s built-in tools. Supply an egress capability for each external model host and give the agent no alternate outbound credential path.
The data-analyst example calls the model API directly. Set OPENAI_API_KEY, OPENAI_INPUT_USD_PER_MILLION_TOKENS, and OPENAI_OUTPUT_USD_PER_MILLION_TOKENS in its image environment before making a model request. The two prices must be positive, finite decimal amounts matching the configured model’s current input and output rates, and must fit the agent’s integer microdollar accounting. The example checks the prices before the request and records the API response’s token usage at those rates before it completes.
Report a result
Callemit.result(summary_markdown, items, coverage, progress=..., assumptions=..., data_freshness=...) before emit.done() to leave a readable report. The three keyword fields are optional. Each item has a stable key, a title, optional status_hint (1 for needs attention, 2 for information, 3 for OK), evidence pairs with label and value, query_refs, and suggested_action. For example, using query_id and newest_order_timestamp from your query:
coverage.withheld=true whenever required checks are incomplete, regardless of progress.
A known
newest_timestamp must use RFC3339 with a timezone, such as 2026-10-30T08:00:00.123456789Z; omit fractional seconds or supply one through nine digits. Supply a nonempty timestamp_column and query_ref with every known timestamp. Report the newest data timestamp seen by that query, never the run clock. A timestamp from filtered rows does not establish whole-table freshness, and a query reference does not grant access or verify a claim.
Use an empty newest_timestamp for unknown freshness, empty or all-null results, a DATE, or a timestamp without a timezone. For a zoneless value, preserve the original observed value and its table, column, and query reference in the summary or coverage note. Never append Z or invent an offset. Keep incomplete required freshness checks disclosed in coverage.
Invalid receipt fields raise ValueError, including when you run against an older Dippr version. A version that supports reports but not these optional fields receives the summary, items, and coverage without the receipt details. Progress and assumptions do not approve writes or change the task’s execution state.
Run a task
An agent task can target a same-tenant plane-local Git repository with a repository UUID, ref, and optional relative source folder. The agent receives a repository-scoped Git credential separate from its engine token. Credentials last no more than 15 minutes and refresh during a long task. Commits use a short-lived SSH signing key and carryagent:<installation/task/turn> provenance.
The agent’s own push event is recorded but does not start the same task again. Other subscribers,
including source indexing and dbt refresh, still receive the update. Revoking the task or the
plane_git entitlement stops later refreshes and pushes. A task launched under a narrowed role cannot
reuse the launcher’s wider repository access.
Installing an agent, setting its consent and budget, and reviewing a paused write happen on the console’s Agents page (Run and review agents); dip has no install or review command. dip agent list shows catalog IDs, not installation IDs, and the console does not display installation IDs: take one from AgentService.ListAgentInstallations. For an existing installation, find a query engine UUID with dip engine list, then run dip agent run <installation-id> --engine-id <uuid> --prompt "your request". By default, the command prints the summary, findings, evidence, and coverage from a successful result first, followed by a Conversation heading and the conversation text, proposal, cost, and state lines. Without a successful result, it prints the conversation and control lines without a heading. Add --json to retain the raw JSON event lines for scripts. Diagnostics go to stderr. The command follows the task’s content stream until it stops or pauses, renewing the viewer capability and resuming from the last event when a long history outlives a stream. Pressing Ctrl-C, sending SIGTERM, or encountering an error after task creation requests remote cancellation while the task is still active. If that request fails, dip prints the task ID and says it may still run. A successful cancel or reject records the task’s final state straight away, but the agent’s sandbox can keep running briefly while it stops, usually within a minute, and the task’s access is removed once it has stopped. Deleting an installation while that clean-up is still running answers “try again”; retry after a few seconds. A proposed write remains in AWAITING_REVIEW until an authorized person reviews it in the console, or a caller whose sign-in holds agents:review uses ReviewAgentTask; agents:run alone cannot.
See CLI command reference for flags.