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.
- dagentos-0.17.0/.gitignore +21 -0
- dagentos-0.17.0/LICENSE +21 -0
- dagentos-0.17.0/PKG-INFO +456 -0
- dagentos-0.17.0/README.md +411 -0
- dagentos-0.17.0/dagentos/__init__.py +1 -0
- dagentos-0.17.0/dagentos/_ui/VERSION +1 -0
- dagentos-0.17.0/dagentos/_ui/assets/index-B7IETFa3.js +12 -0
- dagentos-0.17.0/dagentos/_ui/assets/index-B7IETFa3.js.br +0 -0
- dagentos-0.17.0/dagentos/_ui/assets/index-B7IETFa3.js.gz +0 -0
- dagentos-0.17.0/dagentos/_ui/assets/index-DcqAlFMe.css +1 -0
- dagentos-0.17.0/dagentos/_ui/assets/index-DcqAlFMe.css.br +0 -0
- dagentos-0.17.0/dagentos/_ui/assets/index-DcqAlFMe.css.gz +0 -0
- dagentos-0.17.0/dagentos/_ui/favicon.svg +10 -0
- dagentos-0.17.0/dagentos/_ui/index.html +18 -0
- dagentos-0.17.0/dagentos/agents/__init__.py +1 -0
- dagentos-0.17.0/dagentos/agents/echo.py +26 -0
- dagentos-0.17.0/dagentos/agents/tool.py +264 -0
- dagentos-0.17.0/dagentos/api/__init__.py +1 -0
- dagentos-0.17.0/dagentos/api/auth.py +323 -0
- dagentos-0.17.0/dagentos/api/main.py +599 -0
- dagentos-0.17.0/dagentos/api/stream.py +150 -0
- dagentos-0.17.0/dagentos/api/triggers.py +110 -0
- dagentos-0.17.0/dagentos/api/ui.py +189 -0
- dagentos-0.17.0/dagentos/cli.py +317 -0
- dagentos-0.17.0/dagentos/core/__init__.py +1 -0
- dagentos-0.17.0/dagentos/core/coordination.py +44 -0
- dagentos-0.17.0/dagentos/core/engine.py +1160 -0
- dagentos-0.17.0/dagentos/core/events.py +289 -0
- dagentos-0.17.0/dagentos/core/faults.py +64 -0
- dagentos-0.17.0/dagentos/core/fold.py +225 -0
- dagentos-0.17.0/dagentos/core/integrity.py +68 -0
- dagentos-0.17.0/dagentos/core/models.py +374 -0
- dagentos-0.17.0/dagentos/core/policy.py +199 -0
- dagentos-0.17.0/dagentos/core/ports.py +118 -0
- dagentos-0.17.0/dagentos/core/seal.py +219 -0
- dagentos-0.17.0/dagentos/core/upcast.py +56 -0
- dagentos-0.17.0/dagentos/notify/__init__.py +8 -0
- dagentos-0.17.0/dagentos/notify/slack.py +224 -0
- dagentos-0.17.0/dagentos/observability/__init__.py +100 -0
- dagentos-0.17.0/dagentos/observability/otel.py +303 -0
- dagentos-0.17.0/dagentos/observability/prometheus.py +213 -0
- dagentos-0.17.0/dagentos/plugins.py +84 -0
- dagentos-0.17.0/dagentos/providerkit/__init__.py +79 -0
- dagentos-0.17.0/dagentos/providerkit/cassette.py +116 -0
- dagentos-0.17.0/dagentos/providerkit/config.py +86 -0
- dagentos-0.17.0/dagentos/providerkit/conformance.py +92 -0
- dagentos-0.17.0/dagentos/providerkit/errors.py +49 -0
- dagentos-0.17.0/dagentos/providerkit/pricing.py +62 -0
- dagentos-0.17.0/dagentos/providerkit/prompt.py +79 -0
- dagentos-0.17.0/dagentos/providerkit/schema.py +164 -0
- dagentos-0.17.0/dagentos/providerkit/tools.py +126 -0
- dagentos-0.17.0/dagentos/store/__init__.py +1 -0
- dagentos-0.17.0/dagentos/store/factory.py +31 -0
- dagentos-0.17.0/dagentos/store/memory.py +220 -0
- dagentos-0.17.0/dagentos/store/migrations.py +88 -0
- dagentos-0.17.0/dagentos/store/postgres.py +386 -0
- dagentos-0.17.0/dagentos/store/sqlite.py +392 -0
- dagentos-0.17.0/dagentos/triggers/__init__.py +24 -0
- dagentos-0.17.0/dagentos/triggers/__main__.py +87 -0
- dagentos-0.17.0/dagentos/triggers/config.py +169 -0
- dagentos-0.17.0/dagentos/triggers/cron.py +147 -0
- dagentos-0.17.0/dagentos/triggers/errors.py +8 -0
- dagentos-0.17.0/dagentos/triggers/runner.py +147 -0
- dagentos-0.17.0/dagentos/triggers/webhook.py +70 -0
- dagentos-0.17.0/dagentos/worker/__init__.py +133 -0
- dagentos-0.17.0/dagentos/worker/__main__.py +123 -0
- dagentos-0.17.0/examples/calc_agent.json +1 -0
- dagentos-0.17.0/examples/critic_agent.json +10 -0
- dagentos-0.17.0/examples/critic_typed_agent.json +19 -0
- dagentos-0.17.0/examples/diamond_workflow.json +9 -0
- dagentos-0.17.0/examples/echo_agent.json +1 -0
- dagentos-0.17.0/examples/haiku_workflow.json +9 -0
- dagentos-0.17.0/examples/hello_workflow.json +7 -0
- dagentos-0.17.0/examples/operator_policy.json +10 -0
- dagentos-0.17.0/examples/payer_agent.json +1 -0
- dagentos-0.17.0/examples/poet_agent.json +10 -0
- dagentos-0.17.0/examples/repo_facts_agent.json +11 -0
- dagentos-0.17.0/examples/repo_poet_agent.json +10 -0
- dagentos-0.17.0/examples/research_workflow.json +7 -0
- dagentos-0.17.0/examples/triggers.json +8 -0
- 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
|
dagentos-0.17.0/LICENSE
ADDED
|
@@ -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.
|
dagentos-0.17.0/PKG-INFO
ADDED
|
@@ -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
|
+

|
|
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
|
+

|
|
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
|