dagentos 0.17.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. dagentos-0.17.0/.gitignore +21 -0
  2. dagentos-0.17.0/LICENSE +21 -0
  3. dagentos-0.17.0/PKG-INFO +456 -0
  4. dagentos-0.17.0/README.md +411 -0
  5. dagentos-0.17.0/dagentos/__init__.py +1 -0
  6. dagentos-0.17.0/dagentos/_ui/VERSION +1 -0
  7. dagentos-0.17.0/dagentos/_ui/assets/index-B7IETFa3.js +12 -0
  8. dagentos-0.17.0/dagentos/_ui/assets/index-B7IETFa3.js.br +0 -0
  9. dagentos-0.17.0/dagentos/_ui/assets/index-B7IETFa3.js.gz +0 -0
  10. dagentos-0.17.0/dagentos/_ui/assets/index-DcqAlFMe.css +1 -0
  11. dagentos-0.17.0/dagentos/_ui/assets/index-DcqAlFMe.css.br +0 -0
  12. dagentos-0.17.0/dagentos/_ui/assets/index-DcqAlFMe.css.gz +0 -0
  13. dagentos-0.17.0/dagentos/_ui/favicon.svg +10 -0
  14. dagentos-0.17.0/dagentos/_ui/index.html +18 -0
  15. dagentos-0.17.0/dagentos/agents/__init__.py +1 -0
  16. dagentos-0.17.0/dagentos/agents/echo.py +26 -0
  17. dagentos-0.17.0/dagentos/agents/tool.py +264 -0
  18. dagentos-0.17.0/dagentos/api/__init__.py +1 -0
  19. dagentos-0.17.0/dagentos/api/auth.py +323 -0
  20. dagentos-0.17.0/dagentos/api/main.py +599 -0
  21. dagentos-0.17.0/dagentos/api/stream.py +150 -0
  22. dagentos-0.17.0/dagentos/api/triggers.py +110 -0
  23. dagentos-0.17.0/dagentos/api/ui.py +189 -0
  24. dagentos-0.17.0/dagentos/cli.py +317 -0
  25. dagentos-0.17.0/dagentos/core/__init__.py +1 -0
  26. dagentos-0.17.0/dagentos/core/coordination.py +44 -0
  27. dagentos-0.17.0/dagentos/core/engine.py +1160 -0
  28. dagentos-0.17.0/dagentos/core/events.py +289 -0
  29. dagentos-0.17.0/dagentos/core/faults.py +64 -0
  30. dagentos-0.17.0/dagentos/core/fold.py +225 -0
  31. dagentos-0.17.0/dagentos/core/integrity.py +68 -0
  32. dagentos-0.17.0/dagentos/core/models.py +374 -0
  33. dagentos-0.17.0/dagentos/core/policy.py +199 -0
  34. dagentos-0.17.0/dagentos/core/ports.py +118 -0
  35. dagentos-0.17.0/dagentos/core/seal.py +219 -0
  36. dagentos-0.17.0/dagentos/core/upcast.py +56 -0
  37. dagentos-0.17.0/dagentos/notify/__init__.py +8 -0
  38. dagentos-0.17.0/dagentos/notify/slack.py +224 -0
  39. dagentos-0.17.0/dagentos/observability/__init__.py +100 -0
  40. dagentos-0.17.0/dagentos/observability/otel.py +303 -0
  41. dagentos-0.17.0/dagentos/observability/prometheus.py +213 -0
  42. dagentos-0.17.0/dagentos/plugins.py +84 -0
  43. dagentos-0.17.0/dagentos/providerkit/__init__.py +79 -0
  44. dagentos-0.17.0/dagentos/providerkit/cassette.py +116 -0
  45. dagentos-0.17.0/dagentos/providerkit/config.py +86 -0
  46. dagentos-0.17.0/dagentos/providerkit/conformance.py +92 -0
  47. dagentos-0.17.0/dagentos/providerkit/errors.py +49 -0
  48. dagentos-0.17.0/dagentos/providerkit/pricing.py +62 -0
  49. dagentos-0.17.0/dagentos/providerkit/prompt.py +79 -0
  50. dagentos-0.17.0/dagentos/providerkit/schema.py +164 -0
  51. dagentos-0.17.0/dagentos/providerkit/tools.py +126 -0
  52. dagentos-0.17.0/dagentos/store/__init__.py +1 -0
  53. dagentos-0.17.0/dagentos/store/factory.py +31 -0
  54. dagentos-0.17.0/dagentos/store/memory.py +220 -0
  55. dagentos-0.17.0/dagentos/store/migrations.py +88 -0
  56. dagentos-0.17.0/dagentos/store/postgres.py +386 -0
  57. dagentos-0.17.0/dagentos/store/sqlite.py +392 -0
  58. dagentos-0.17.0/dagentos/triggers/__init__.py +24 -0
  59. dagentos-0.17.0/dagentos/triggers/__main__.py +87 -0
  60. dagentos-0.17.0/dagentos/triggers/config.py +169 -0
  61. dagentos-0.17.0/dagentos/triggers/cron.py +147 -0
  62. dagentos-0.17.0/dagentos/triggers/errors.py +8 -0
  63. dagentos-0.17.0/dagentos/triggers/runner.py +147 -0
  64. dagentos-0.17.0/dagentos/triggers/webhook.py +70 -0
  65. dagentos-0.17.0/dagentos/worker/__init__.py +133 -0
  66. dagentos-0.17.0/dagentos/worker/__main__.py +123 -0
  67. dagentos-0.17.0/examples/calc_agent.json +1 -0
  68. dagentos-0.17.0/examples/critic_agent.json +10 -0
  69. dagentos-0.17.0/examples/critic_typed_agent.json +19 -0
  70. dagentos-0.17.0/examples/diamond_workflow.json +9 -0
  71. dagentos-0.17.0/examples/echo_agent.json +1 -0
  72. dagentos-0.17.0/examples/haiku_workflow.json +9 -0
  73. dagentos-0.17.0/examples/hello_workflow.json +7 -0
  74. dagentos-0.17.0/examples/operator_policy.json +10 -0
  75. dagentos-0.17.0/examples/payer_agent.json +1 -0
  76. dagentos-0.17.0/examples/poet_agent.json +10 -0
  77. dagentos-0.17.0/examples/repo_facts_agent.json +11 -0
  78. dagentos-0.17.0/examples/repo_poet_agent.json +10 -0
  79. dagentos-0.17.0/examples/research_workflow.json +7 -0
  80. dagentos-0.17.0/examples/triggers.json +8 -0
  81. dagentos-0.17.0/pyproject.toml +134 -0
@@ -0,0 +1,21 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ venv/
5
+ .env
6
+ .pytest_cache/
7
+ .ruff_cache/
8
+ *.egg-info/
9
+ .DS_Store
10
+ dist/
11
+ build/
12
+ # operator UI bundle copied into the package for the wheel (scripts/bundle_ui.py)
13
+ dagentos/_ui/
14
+
15
+ # local SQLite store (default AGENTOS_STORE=sqlite)
16
+ agentos.db
17
+ agentos.db-wal
18
+ agentos.db-shm
19
+
20
+ # uv lockfile: no job verifies it (CI installs with pip), so a stray `uv lock` must not be committed
21
+ uv.lock
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Amit Singh
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,456 @@
1
+ Metadata-Version: 2.5
2
+ Name: dagentos
3
+ Version: 0.17.0
4
+ Summary: A control plane for durable, observable, human-in-the-loop LLM agent workflows
5
+ Project-URL: Homepage, https://github.com/AmitSinghOM/AgentOS
6
+ Project-URL: Repository, https://github.com/AmitSinghOM/AgentOS
7
+ Project-URL: Changelog, https://github.com/AmitSinghOM/AgentOS/releases
8
+ Project-URL: Documentation, https://github.com/AmitSinghOM/AgentOS/blob/main/README.md
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: agents,durable-execution,event-sourcing,human-in-the-loop,llm,workflow
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
21
+ Classifier: Typing :: Typed
22
+ Requires-Python: >=3.11
23
+ Requires-Dist: anyio>=4
24
+ Requires-Dist: fastapi>=0.110
25
+ Requires-Dist: httpx>=0.27
26
+ Requires-Dist: psycopg-pool>=3.2
27
+ Requires-Dist: psycopg[binary]>=3.1
28
+ Requires-Dist: pydantic>=2.6
29
+ Requires-Dist: uvicorn[standard]>=0.29
30
+ Provides-Extra: dev
31
+ Requires-Dist: httpx>=0.27; extra == 'dev'
32
+ Requires-Dist: import-linter>=2.0; extra == 'dev'
33
+ Requires-Dist: pytest>=8.0; extra == 'dev'
34
+ Requires-Dist: ruff>=0.4; extra == 'dev'
35
+ Provides-Extra: observability
36
+ Requires-Dist: opentelemetry-api>=1.25; extra == 'observability'
37
+ Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == 'observability'
38
+ Requires-Dist: opentelemetry-sdk>=1.25; extra == 'observability'
39
+ Requires-Dist: opentelemetry-semantic-conventions>=0.46b0; extra == 'observability'
40
+ Requires-Dist: prometheus-client>=0.20; extra == 'observability'
41
+ Provides-Extra: providerkit
42
+ Requires-Dist: httpx>=0.27; extra == 'providerkit'
43
+ Requires-Dist: jsonschema<5,>=4.20; extra == 'providerkit'
44
+ Description-Content-Type: text/markdown
45
+
46
+ # AgentOS
47
+
48
+ **A control plane for durable, observable, human-in-the-loop LLM agent workflows.**
49
+
50
+ Define a workflow as a DAG of agent steps. AgentOS runs it durably — surviving crashes,
51
+ recording exactly one committed completion per step (a step that ran but did not commit
52
+ before a crash is re-run, so external effects rely on downstream idempotency — see
53
+ [FAIL_MODES.md](./docs/FAIL_MODES.md)), pausing for human approval, and emitting a full
54
+ trace and cost breakdown for every run.
55
+
56
+ The interesting part isn't calling LLMs. It's the distributed-systems layer around them:
57
+ **durable execution, idempotency, retries without corruption, suspended workflows, and
58
+ observability.** See [DESIGN.md](./DESIGN.md) for the architecture and the decisions
59
+ behind it.
60
+
61
+ ---
62
+
63
+ ## Why this exists
64
+
65
+ A notebook chaining three agent calls works until something real happens — the process
66
+ crashes mid-run, a model call times out, a step needs sign-off, or you need to explain
67
+ why run #4821 cost $2.10. AgentOS handles those.
68
+
69
+ ## What it looks like running
70
+
71
+ One trace per run, derived from the event log. This one wrote a haiku on a local model,
72
+ suspended for a human's approval of a `spend` step, waited, and resumed after the grant —
73
+ the gap is the human:
74
+
75
+ ![Jaeger: a run suspended for approval, then resumed](docs/images/jaeger-run-payment.png)
76
+
77
+ The provisioned Grafana dashboard, from the same log: runs per minute, error rate, latency
78
+ percentiles, step outcomes, retries and dead-letters, tokens by executor, approval wait,
79
+ cost by workflow. Every number is a fold of events — replaying the log rebuilds it exactly.
80
+
81
+ ![Grafana: the AgentOS dashboard](docs/images/grafana-dashboard.png)
82
+
83
+ Both are from a real two-process run (API + worker) against Ollama — see
84
+ [`docs/quickstart-llm.md`](docs/quickstart-llm.md) §7 to reproduce them.
85
+
86
+ ## Architecture (at a glance)
87
+
88
+ ```mermaid
89
+ flowchart TD
90
+ C[Client] -->|define / start / approve| API[FastAPI API]
91
+ API -->|append run.started, enqueue| PG[(PostgreSQL or SQLite<br/>event log · queue · leases · blobs)]
92
+ PG --> W[Worker<br/>fenced lease, wave scheduler]
93
+ W --> EXEC[Executors]
94
+ EXEC --> PROV[Provider plugins<br/>openai-compat · anthropic · openai-agents · pydantic-ai · acp]
95
+ EXEC --> TOOL[tool<br/>HTTP · subprocess]
96
+ W -->|append events| PG
97
+ PG -.observers derive.-> OTEL[OpenTelemetry → Jaeger]
98
+ PG -.observers derive.-> PROM[Prometheus → Grafana]
99
+ ```
100
+
101
+ One store is the whole truth: the append-only, hash-chained event log, plus the queue,
102
+ fenced leases and content-addressed blobs, behind one `Store` port with PostgreSQL, SQLite
103
+ and in-memory adapters. There is no second system to keep consistent. Snapshots bound
104
+ replay cost and are only a cache of the fold.
105
+
106
+ ## Quick start
107
+
108
+ Three paths. **With a real model, no API key** (recommended): [`docs/quickstart-llm.md`](docs/quickstart-llm.md) —
109
+ Ollama + the `openai-compat` provider, five minutes, a poet and a critic on your laptop.
110
+ **The approval gate, end to end**: [`docs/tutorial.md`](docs/tutorial.md) — a run that suspends
111
+ before a `spend` step, decided as a named human, then the log that proves it and a rewind to the
112
+ moment it stopped; ten minutes, no model. **Without any model** (the mechanics only), below.
113
+
114
+ ```bash
115
+ cp .env.example .env
116
+ pip install -e ".[dev]"
117
+ uvicorn dagentos.api.main:app --reload # API (SQLite file ./agentos.db by default)
118
+ python -m dagentos.worker # worker, in another terminal
119
+ ```
120
+
121
+ Installing rather than cloning: distribution and import package are both **`dagentos`**
122
+ (`pip install dagentos` → `import dagentos`). The product is AgentOS; the name `agentos` on PyPI
123
+ belongs to an unrelated project, so the package carries a `d` for durable. The `AGENTOS_*`
124
+ environment variables and the `agentos` CLI keep the product name.
125
+ Every release ships wheels with Sigstore-signed provenance and a multi-arch image built from the
126
+ same wheels — verification in [`docs/RELEASING.md`](docs/RELEASING.md).
127
+
128
+ ```bash
129
+ pip install "dagentos[providerkit]" agentos-provider-openai-compat
130
+ docker run --rm -p 127.0.0.1:8000:8000 ghcr.io/amitsinghom/agentos # API on loopback; python -m dagentos.worker for the worker
131
+ ```
132
+
133
+ A whole coding agent as a step: [`providers/acp`](providers/acp/README.md) runs one
134
+ [Agent Client Protocol](https://agentclientprotocol.com) turn (`kiro-cli acp` by default, any
135
+ ACP agent by config) under the same gate — the agent's permission prompts are answered from
136
+ the step's declared effect classes, never `allow_always`, and an unasked undeclared tool
137
+ dead-letters the step.
138
+
139
+ No Docker needed for the default SQLite store. For Postgres (needs the `.env` from above —
140
+ the compose file reads `POSTGRES_PASSWORD` from it and refuses to start without one):
141
+ `docker compose up -d`, then `AGENTOS_STORE=postgres AGENTOS_PG_DSN=postgresql://agentos:agentos@localhost/agentos`
142
+ for both processes.
143
+
144
+ Define and run a workflow (the `Content-Type` header matters — without it curl sends a
145
+ form body and the API answers 422):
146
+
147
+ ```bash
148
+ # register an agent
149
+ curl -X POST localhost:8000/agents -H 'Content-Type: application/json' -d @examples/echo_agent.json
150
+
151
+ # define a workflow
152
+ curl -X POST localhost:8000/workflows -H 'Content-Type: application/json' -d @examples/hello_workflow.json
153
+
154
+ # start a run: 202 + run id; the worker advances it. Repeating with the same
155
+ # Idempotency-Key returns the same run.
156
+ curl -X POST localhost:8000/workflows/hello/runs -H 'Idempotency-Key: demo-1'
157
+
158
+ # fetch the folded state, or the raw event log paged by seq
159
+ curl localhost:8000/runs/{run_id}
160
+ curl 'localhost:8000/runs/{run_id}/events?after=0'
161
+
162
+ # a step that exhausted its retries is dead-lettered with the cause; reopen it,
163
+ # recording who asked, and the run continues from where it stopped
164
+ curl -X POST localhost:8000/runs/{run_id}/steps/{step_id}/retry \
165
+ -H 'Content-Type: application/json' \
166
+ -d '{"principal": {"kind": "human", "id": "amit"}, "reason": "fixed the agent"}'
167
+
168
+ # operator control: each is a persisted request, finalized at the worker's next
169
+ # boundary (or immediately if nothing is running). Completed steps are never lost.
170
+ curl -X POST localhost:8000/runs/{run_id}/pause
171
+ curl -X POST localhost:8000/runs/{run_id}/resume
172
+ curl -X POST localhost:8000/runs/{run_id}/cancel
173
+
174
+ # human-in-the-loop: a step whose agent declares spend / write_external / send_message /
175
+ # execute_code suspends the run BEFORE it runs. Decide from the inbox; the decision and
176
+ # who made it are in the log; the step then runs, and its completion is committed once.
177
+ curl localhost:8000/approvals
178
+ curl -X POST localhost:8000/runs/{run_id}/approvals/{approval_id}/approve \
179
+ -H 'Content-Type: application/json' \
180
+ -d '{"principal": {"kind": "human", "id": "amit"}, "reason": "within budget"}'
181
+
182
+ # or run synchronously in the API process (Phase 0 behaviour)
183
+ curl -X POST 'localhost:8000/workflows/hello/runs?sync=true'
184
+ ```
185
+
186
+ Or run the same walkthrough as a test: `pytest tests/test_quickstart.py`.
187
+
188
+ ## What people use it for
189
+
190
+ AgentOS is for the agent work that has to be **accountable**: it spends money, writes to a
191
+ system someone else depends on, or has to be explained afterwards to a person who was not
192
+ there. Each use case below is one declared workflow; the files named are in
193
+ [`examples/`](examples/) and run against the quick start.
194
+
195
+ | Use case | The shape | Where the ledger earns its keep |
196
+ |---|---|---|
197
+ | **Content pipeline with a reviewer** — write, then critique, then ship | two `llm` steps: `poet` writes, `critic` reviews with `depends_on: ["write"]` and a `retry` policy ([`haiku_workflow.json`](examples/haiku_workflow.json)); `critic_typed_agent.json` makes the review a typed `{score, reason}` via `output_schema` | `budget.max_run_cost` caps the whole run; a flaky model is retried per node and dead-lettered with the cause, not silently dropped |
198
+ | **Research, then write** — pull facts from an API, hand them to a model | a `tool` step (`kind: http`, effect `read`) feeding an `llm` step ([`research_workflow.json`](examples/research_workflow.json)); the URL is the operator's and inputs reach the tool as values only, never as URL or argv | the response body (capped at 1 MiB, header values redacted) is the step's recorded output, so the writer's prompt is reproducible after the API changes |
199
+ | **Anything that spends or ships** — payment, deploy, outbound email | any node whose agent declares `spend`, `write_external`, `send_message` or `execute_code` ([`diamond_workflow.json`](examples/diamond_workflow.json) with `payer_agent.json`) | the run **suspends before the step runs**; a named human approves from the inbox or the API; who, when and why are in the hash-chained log; the step's completion is then committed once |
200
+ | **A coding agent as one step** — fix a failing test, open a change | one `llm` step with `executor: acp` declaring `[compute, read, execute_code]` ([`providers/acp`](providers/acp/README.md)); the agent's permission prompts are answered from that declaration | an unasked edit outside the declaration dead-letters the step; every tool call is recorded by SHA-256; no `allow_always` ever |
201
+ | **Scheduled and event-driven runs** — nightly reports, "on every push" | `python -m dagentos.triggers` with cron slots (IANA time zones) and HMAC-signed webhooks ([`triggers.json`](examples/triggers.json)) | every trigger goes through the public run-start API with a derived `Idempotency-Key`, so a redelivered webhook or a retried slot is one run |
202
+ | **Comparing models or harnesses** — same task, different backend | one workflow, `executor` swapped between `openai-compat`, `anthropic`, `openai-agents`, `pydantic-ai` and `acp`; the two API providers share one output shape and the two SDK harnesses another, each pinned by a test | the cost panel and `provenance.model_id` make the comparison a query over runs, not a spreadsheet |
203
+
204
+ If the work is a conversation with an agent that should remember you, that is a workspace
205
+ product (Kiro CLI, Kiro Crew) — AgentOS runs *its* agent as a step when the step needs the
206
+ ledger, and stays out of the way otherwise.
207
+
208
+ ## Using it with popular models
209
+
210
+ Every model touches the core through one seam, the `Executor` port, so the choice of model
211
+ is an agent-definition field plus environment variables — never a code change. Two agents in
212
+ the same workflow can use two vendors.
213
+
214
+ | Backend | `executor` | Environment | `config.model` |
215
+ |---|---|---|---|
216
+ | **Ollama** (local, the default) | `openai-compat` | none — `ollama serve` on `127.0.0.1:11434`, `ollama pull qwen2.5:0.5b` | alias `chat.fast` → `qwen2.5:0.5b`, `chat.default` → `llama3.2:3b` |
217
+ | **OpenAI** (`gpt-4.1`, `gpt-4o`, `o3-mini`, …) | `openai-compat` | `AGENTOS_OPENAI_BASE_URL=https://api.openai.com/v1` and `OPENAI_API_KEY` | a concrete id, or re-point the aliases: `AGENTOS_OPENAI_ALIASES='{"chat.fast":"gpt-4o-mini","chat.default":"gpt-4.1"}'` |
218
+ | **Anthropic** (`claude-sonnet-4`, `claude-3-5-haiku-latest`, …) | `anthropic` | `AGENTOS_ANTHROPIC_BASE_URL=https://api.anthropic.com` (no `/v1`) and `ANTHROPIC_API_KEY` | `AGENTOS_ANTHROPIC_ALIASES='{"chat.fast":"claude-3-5-haiku-latest","chat.default":"claude-sonnet-4"}'` |
219
+ | **Google Gemini** | `openai-compat` | `AGENTOS_OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai` and `AGENTOS_OPENAI_API_KEY=<Gemini key>` | e.g. `gemini-2.5-flash` — any id the endpoint lists |
220
+ | **OpenRouter** (hundreds of models behind one key) | `openai-compat` | `AGENTOS_OPENAI_BASE_URL=https://openrouter.ai/api/v1` and `AGENTOS_OPENAI_API_KEY` | the router's `vendor/model` id, as its `GET /models` lists it |
221
+ | **vLLM / LM Studio / any OpenAI-compatible server** | `openai-compat` | `AGENTOS_OPENAI_BASE_URL=http://host:8000/v1` (vLLM) or `http://127.0.0.1:1234/v1` (LM Studio) | whatever the server reports at `GET /models` |
222
+ | **An agent SDK with tools** (OpenAI Agents SDK, PydanticAI) | `openai-agents` / `pydantic-ai` | same shape with the `AGENTOS_OPENAI_AGENTS_*` / `AGENTOS_PYDANTIC_AI_*` prefix; both default to local Ollama | alias or id; `tools` names registered operator functions, each with an effect class |
223
+ | **A whole coding agent** (Kiro CLI, Gemini CLI, Claude Code via its ACP adapter, …) | `acp` | `AGENTOS_ACP_COMMAND='["kiro-cli","acp"]'` (default) plus the agent's own login | ignored — the agent brings its model |
224
+
225
+ The same poet, three ways. Only `executor` (and the environment above) changes:
226
+
227
+ ```json
228
+ {"name": "poet", "type": "llm", "executor": "openai-compat",
229
+ "config": {"model": "chat.fast", "system": "You are a terse poet.",
230
+ "prompt": "Write a haiku about {run.topic}."}}
231
+ ```
232
+
233
+ ```json
234
+ {"name": "poet", "type": "llm", "executor": "anthropic",
235
+ "config": {"model": "claude-3-5-haiku-latest", "system": "You are a terse poet.",
236
+ "prompt": "Write a haiku about {run.topic}."}}
237
+ ```
238
+
239
+ ```json
240
+ {"name": "poet", "type": "llm", "executor": "pydantic-ai", "declared_effects": ["compute"],
241
+ "config": {"model": "gpt-4o-mini", "instructions": "You are a terse poet.",
242
+ "prompt": "Write a haiku about {run.topic}.", "tools": ["utc_now"]}}
243
+ ```
244
+
245
+ Mixing vendors in one run is the same file twice: register the Anthropic poet and an OpenAI
246
+ critic, and `haiku_workflow.json` runs unchanged. `GET /executors` shows each backend's health
247
+ (server reachable, aliases resolvable to models it actually has) before you start a run.
248
+
249
+ What the log records is the same for all of them: the concrete `model_id` the server reported
250
+ (not the alias you asked for), token usage, and a `cost` metered through a content-addressed
251
+ pricing table whose hash is on every step. OpenAI and Anthropic ids in the bundled tables are
252
+ priced; anything else (Gemini, OpenRouter, a local model) is recorded with its meters and
253
+ `priced: false` until you point `AGENTOS_OPENAI_PRICING` / `AGENTOS_ANTHROPIC_PRICING` at your own
254
+ table — the amount is never guessed. A misconfiguration is a `ConfigError` naming the variable;
255
+ an unreachable server, a missing model or a bad key is a `step.failed` whose message says what
256
+ to do (`ollama pull …`, set the key), then the node's retry policy, then a dead-letter with that
257
+ message as the cause. Full per-provider tables: [`providers/*/README.md`](providers/).
258
+
259
+ ### Authentication
260
+
261
+ The quick start runs with `AGENTOS_AUTH=asserted` (the default): the `principal` in a
262
+ request body is recorded as given and **nothing verifies it** — the API says so in a
263
+ startup warning. Before anyone else can reach the API, switch to bearer mode, where the
264
+ credential decides who the caller is and the body may not:
265
+
266
+ ```bash
267
+ # one line per principal; the file holds SHA-256 hashes, never tokens
268
+ TOKEN=$(openssl rand -hex 32)
269
+ printf '{"principals": [{"sha256": "%s", "kind": "human", "id": "amit"}]}\n' \
270
+ "$(printf %s "$TOKEN" | shasum -a 256 | cut -d' ' -f1)" > tokens.json
271
+ AGENTOS_AUTH=bearer AGENTOS_AUTH_TOKENS=tokens.json uvicorn dagentos.api.main:app
272
+
273
+ # every request except /health, /ready and /metrics needs the token; decisions drop the body principal
274
+ curl -X POST localhost:8000/runs/{run_id}/approvals/{approval_id}/approve \
275
+ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
276
+ -d '{"reason": "within budget"}'
277
+ ```
278
+
279
+ The recorded principal on `approval.granted` is the token's (`kind`, `id`, and an
280
+ `attestation` naming which credential, `token:sha256:<12 hex>`), a body `principal` is
281
+ rejected 422 rather than silently replaced, an `agent`-kind token can neither approve a
282
+ `spend` step (403) nor register agents or define workflows (403), and every rejection is
283
+ logged by hash prefix only. Rotate by editing the file and restarting. Tests:
284
+ `tests/test_auth.py`; contract: `docs/TRUST_BOUNDARY.md` §1. Which way every chokepoint fails,
285
+ with the test that pins it: `docs/FAIL_MODES.md`.
286
+
287
+ ### Operator policy ceiling
288
+
289
+ Every limit the gate enforces comes from the workflow's `budget` — written by whoever defines
290
+ the workflow. The operator's rules live in one file that every workflow budget is intersected
291
+ with before the gate sees it. Tightest wins; a policy can only narrow:
292
+
293
+ ```bash
294
+ AGENTOS_POLICY=examples/operator_policy.json uvicorn dagentos.api.main:app # and the worker
295
+ curl localhost:8000/policy # the ceiling and its sha256
296
+ ```
297
+
298
+ `effect_ceiling` is the set of effect classes any step may ever run (outside it → refused
299
+ before dispatch, whatever the workflow says); `always_approve` forces a decision even where a
300
+ workflow allows a class freely; `agent_approval_allowed: false` revokes `allow_agent_approval`
301
+ everywhere, including on the approve path; `allowed_executors` fails a run at dispatch if an
302
+ agent names anything else; the cost and wall limits are minimums. Each run records
303
+ `governance.policy_applied` right after `run.started` with the policy's sha256 and every
304
+ narrowing, so the log says which ceiling governed it. No `AGENTOS_POLICY` → no ceiling and a
305
+ startup warning. Tests: `tests/test_policy.py`.
306
+
307
+ ### Operator UI
308
+
309
+ The API serves a small React app at `/ui` — in the wheel and the image, no Node at runtime —
310
+ with three screens: the **approvals inbox**, the **run list** (status filter held in the URL),
311
+ and the **run page**: the DAG laid out by dagre with each node's state read from the server's
312
+ folded run, the live stream as the trigger for refetches, a timeline with **time travel**
313
+ (`GET /runs/{id}?at=k`, folded on the server, never in the browser), cost and latency per node,
314
+ Pause / Resume / Cancel and per-step retry that mirror the engine's 409 rules, an integrity
315
+ verdict chip from `GET /runs/{id}/integrity`, and decisions in place with the same
316
+ `ApprovalCard` the inbox uses. Every decision control shows exactly who the log will name
317
+ first (`GET /me`; in `asserted` mode the banner says **Unverified** and makes you type a
318
+ principal), keeps the bearer token in the tab's `sessionStorage` only, sends the API's own
319
+ bodies, and shows the API's errors verbatim. Three runtime dependencies, a ~325 kB bundle, a
320
+ strict CSP (`frame-ancestors 'none'`) on every `/ui` response. Building from a checkout:
321
+ `cd ui && npm ci && npm run build`; the contract and what the UI deliberately does not do are
322
+ in [`docs/UI.md`](docs/UI.md), and [`docs/tutorial.md`](docs/tutorial.md) drives all three
323
+ screens in ten minutes.
324
+
325
+ ### Triggers: cron and webhooks
326
+
327
+ Runs can start without a person at a terminal, through the same `POST /workflows/{name}/runs`
328
+ everything else uses — no second door into the engine:
329
+
330
+ ```bash
331
+ AGENTOS_TRIGGERS=triggers.json uvicorn dagentos.api.main:app # mounts POST /triggers/webhooks/{name}
332
+ AGENTOS_TRIGGERS=triggers.json python -m dagentos.triggers # fires the cron triggers
333
+ ```
334
+
335
+ A cron slot becomes `Idempotency-Key: cron:{name}:{slot}`, a webhook delivery becomes
336
+ `webhook:{name}:{delivery-id}`, so a restarted runner or a redelivered webhook lands on the
337
+ same run. Webhooks are signed Stripe-style (`X-AgentOS-Timestamp` + HMAC-SHA256
338
+ `X-AgentOS-Signature`, ±300 s), the secret comes from an environment variable the file
339
+ names, and an unset secret stops the API at startup rather than mounting an unsignable
340
+ route. Missed cron slots are never backfilled. Contract, file format and every fail mode in
341
+ [`docs/triggers.md`](docs/triggers.md).
342
+
343
+ ### Approval notices in Slack
344
+
345
+ ```bash
346
+ AGENTOS_SLACK_WEBHOOK=https://hooks.slack.com/services/T…/B…/… python -m dagentos.worker
347
+ ```
348
+
349
+ When a run suspends for a human, the channel gets the workflow, step, effect class, reason
350
+ and a link to the run page; when someone decides, it gets who and why. The message carries
351
+ **no authority** — no approve button, no token — because an incoming webhook can verify
352
+ nobody; the decision stays in the UI or API where the principal is. Posts happen off the
353
+ engine's thread on a bounded queue, and Slack being down is a warning, never a failed run.
354
+ [`docs/notifications.md`](docs/notifications.md).
355
+
356
+ ### Sealed chains and the `agentos` CLI
357
+
358
+ The hash chain makes edits visible; it cannot stop someone with database access from
359
+ rewriting an idle run and recomputing every hash. With a keyring configured, every event that
360
+ leaves a run idle is followed in the same batch by a seal — an HMAC under a key the database
361
+ host never sees — so a rewrite needs the key and a deleted seal shows as an unsigned tail:
362
+
363
+ ```bash
364
+ printf '{"active": "k1", "keys": {"k1": "%s"}}\n' "$(openssl rand -hex 32)" > signing-keys.json
365
+ AGENTOS_SIGNING_KEYS=signing-keys.json uvicorn dagentos.api.main:app # and the worker
366
+
367
+ agentos verify # every run: chain + seals; exit 1 on any failure
368
+ agentos doctor # store, migrations, executors, auth/policy/signing, every run
369
+ agentos policy explain hello # what the operator ceiling does to one workflow, per node
370
+ ```
371
+
372
+ `GET /runs/{id}/integrity` reports the same seal state (`unsigned | verified | unverifiable |
373
+ INVALID`). Limits, stated plainly in `docs/TRUST_BOUNDARY.md` §2: the key is symmetric (keep it
374
+ off the DB host), and nothing in the log can detect truncation *after* the last seal — the CLI
375
+ reports the uncovered tail instead of pretending. Tests: `tests/test_seal_and_cli.py`.
376
+
377
+ ### Observability
378
+
379
+ Telemetry is derived from the event log, so it can be rebuilt from any stored run and the
380
+ core imports no telemetry SDK.
381
+
382
+ ```bash
383
+ pip install -e ".[observability]"
384
+ docker compose up -d jaeger prometheus grafana
385
+ AGENTOS_OTEL_EXPORTER=otlp OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
386
+ uvicorn dagentos.api.main:app # and the worker, with the same two variables
387
+ ```
388
+
389
+ - Traces: [Jaeger](http://localhost:16686) — one span per run, one per step attempt, with
390
+ OpenTelemetry GenAI attributes (`gen_ai.system`, `gen_ai.request.model`,
391
+ `gen_ai.usage.*_tokens`) plus `agentos.*` (effects declared/reported, cost, approval and
392
+ dead-letter events).
393
+ - Metrics: `GET /metrics` on the API, scraped by [Prometheus](http://localhost:9090).
394
+ - Dashboard: [Grafana](http://localhost:3000), provisioned — runs/min, error rate, runs
395
+ awaiting approval, total cost, latency p50/p95/p99, step outcomes, retries and
396
+ dead-letters, tokens by agent, approval wait, cost per minute by workflow.
397
+
398
+ ### The crash demo, as a test
399
+
400
+ ```bash
401
+ pytest tests/chaos/test_kill9_real_process.py -v
402
+ ```
403
+
404
+ A real worker process is started, hard-killed (exit 137) right after step 2 of 3 is
405
+ committed, and a second process picks the run up and finishes it. The test asserts step 2
406
+ is never started again and the log has exactly one completion per step. Every fault point
407
+ in the commit path has a test in `tests/chaos/`; they run on every PR.
408
+
409
+ ## Roadmap
410
+
411
+ This is built in public, in phases, each ending in a tagged release and a writeup.
412
+ See [ROADMAP.md](./ROADMAP.md).
413
+
414
+ | Phase | Ships | Status |
415
+ |-------|-------|--------|
416
+ | 0 · Walking skeleton | API + Postgres up, single-step run end-to-end | ✅ `v0.1.0-skeleton` |
417
+ | 1 · Durable execution | Event-sourced state, idempotent steps, crash-resume | ✅ `v0.2.0-durable` |
418
+ | 2 · DAG orchestration | Parallel branches, agent versioning, retries + DLQ | ✅ `v0.3.0-dag` |
419
+ | 3 · HITL + observability | Approval gates, OpenTelemetry, cost dashboard | ✅ `v0.4.0-observable` |
420
+ | 4 · Providers + DX | OpenAI-compatible + Anthropic plugins, aliases, cassettes, 5-minute quickstart | ✅ `v0.5.0-providers` |
421
+ | 5 · Trust boundary + polish | C12: strict control payloads, tamper-evident log, inputs as data; screenshots | ✅ `v0.6.0-trusted` |
422
+ | 6 · Tools, snapshots, survey close-out | `tool` agent, verified snapshots + migrations, all 15 `landscape-con` issues closed with tests | ✅ `v0.7.0-complete` |
423
+ | 7 · Streaming + inner harness | `GET /runs/{id}/stream` (SSE over the log), OpenAI Agents SDK and PydanticAI as governed steps | ✅ `v0.8.0-watchable`, `v0.8.1` |
424
+ | 8 · Pilot readiness | Authenticated `Principal`, operator policy ceiling, sealed chains + `agentos verify` / `doctor` / `policy explain`, FAIL_MODES, publishing with provenance as `agentos-durable` (renamed `dagentos` in v0.11.0) | ✅ `v0.9.0-pilot` |
425
+ | 9 · UI | Approvals inbox, live run graph over the stream, timeline with time travel, cost + latency — served at `/ui`, in the wheel and image | ✅ `v0.10.0-ui`, detailed in `v0.12.0`, production passes in `v0.13.0` and `v0.14.0`, shell in `v0.15.0`, run controls, in-place decisions, first-hour tutorial and four-seat review in `v0.16.0` |
426
+ | 10 · Triggers, notifier, ACP, hardening | Cron runner + HMAC-signed webhooks through the public run-start API, Slack approval notices that carry no authority, a whole ACP coding agent as one governed step, compose and image on loopback with no literal credential, asserted-mode tool deny, first PyPI release | ✅ `v0.17.0` |
427
+
428
+ Phases 1–3 are scoped against a survey of what the popular agent runtimes get wrong
429
+ (LangGraph, agno, Microsoft Agent Framework, crewAI, ADK, mastra, Temporal, Hatchet…).
430
+ Each gap is a tracked issue labelled `landscape-con`; see [ROADMAP.md](./ROADMAP.md).
431
+
432
+ ## Engineering writeups
433
+
434
+ Each phase produces an article on a distributed-systems problem solved here:
435
+ - Idempotency Beyond API Keys
436
+ - Durable Execution: Resuming Workflows After a Crash
437
+ - Retry Without Data Corruption
438
+ - Suspended Workflows: Human Approval as a First-Class State
439
+ - Providers Are Plugins
440
+ - Three Doors: Where Untrusted Bytes Meet an Agent Engine
441
+ - Snapshots That Are Never the Truth
442
+ - The Stream Is the Log
443
+
444
+ (See [`docs/blog/`](./docs/blog).)
445
+
446
+ ## Security
447
+
448
+ Report vulnerabilities privately through GitHub's Security Advisory form; scope, supported
449
+ versions and response times are in [`SECURITY.md`](SECURITY.md). Dependabot watches every
450
+ distribution, the UI and the workflow actions; CI runs `pip-audit --strict` and
451
+ `npm audit --audit-level=high` on every pull request. Release artifacts carry build
452
+ provenance (`gh attestation verify`).
453
+
454
+ ## License
455
+
456
+ MIT