A Dippr agent is a program that works on a task using access granted at installation and the access of the person who launched it. You publish an image and a manifest, then an administrator installs it.

Build and publish

  1. Write a Python Agent with manifest(), execute(spec, emit, ctx), and finalize(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, which finalize reads as spec.ctx.resume_state. Pass resume_state= to checkpoint something else. A proposal with an empty checkpoint is refused.
  2. Save manifest().json() as manifest.json next to agent.py. The SDK produces stable bytes so you can check the published declaration against the source.
  3. Install grpcio and protobuf into the Python environment that runs python3, for example with python3 -m pip install 'grpcio>=1.71,<2' 'protobuf>=5.29,<6'. Run the SDK’s conformance harness, then dip agent dev --prompt "hello" to exercise one local turn against the agent runtime. The local turn uses the manifest’s timeoutMin budget. Omit the prompt to leave the runtime serving for manual calls. For a live local SQL or egress turn, supply ALTIMATE_AGENT_DEV_TOKEN and the corresponding --trinoproxy-url or --egress-proxy-url; the default local token is only a placeholder.
  4. Run dip agent build, then dip agent push. Publishing needs apps:publish for the image and agents:publish for 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 run dip agent push again; the catalog is updated through UpdateAgent.
An agent directory with no Dockerfile needs nothing else: 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:
Without it the approved task ends 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

Call emit.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:
Reports can contain at most 10 items. Dippr validates the report and refuses reports with keys over 128 characters, titles over 300 characters, summaries over 20,000 characters, more than 5 evidence pairs per item, evidence labels over 80 characters, evidence values or suggested actions over 500 characters, coverage notes over 1,000 characters, more than 5 query references per item, or query references over 128 characters. Keys must be non-empty and unique in the report. Limits count Unicode characters. A report larger than the 512 KiB size limit is refused. On a Dippr version without report support, the report is not shown and the run still completes. A report is final only after the task succeeds. Reports from failed, cancelled, paused, or incomplete runs remain provisional. A coverage note discloses limitations; it never exposes a count of hidden records. Suggested actions and status hints do not approve or execute changes. The optional receipt fields describe what your agent reports. Dippr checks their format and limits; it does not verify their factual accuracy. Keep 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 carry agent:<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.