Skip to content

Commit f8ea416

Browse files
docs: complete code-aligned documentation audit
1 parent e1d40b1 commit f8ea416

20 files changed

Lines changed: 330 additions & 150 deletions

‎docs/FRONTEND_API_GUIDE.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -78,9 +78,14 @@ interface UpdateThreadRequest {
7878
// ── Feedback ────────────────────────────────────────────────────
7979

8080
interface FeedbackPayload {
81-
thread_id: string;
82-
rating: number; // e.g. 1–5
83-
comment?: string;
81+
user_id?: string; // default: "anonymous"
82+
rating?: number | null; // 1–5 when supplied
83+
comment?: string | null;
84+
correction?: string | null;
85+
feedback_type?: "thumbs" | "rating" | "correction" | "comment";
86+
query?: string;
87+
response?: string;
88+
thread_id?: string | null;
8489
metadata?: Record<string, any>;
8590
}
8691

‎docs/architecture/api-reference.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,7 @@ curl -X POST http://localhost:8000/api/v1/my_agent/invoke \
160160
| Field | Type | Description |
161161
|---|---|---|
162162
| `response` | `string` | Agent response text |
163+
| `output` | `any \| null` | Structured `state_to_output()` payload when available |
163164
| `agent_type` | `string` | Agent slug identifier |
164165
| `thread_id` | `string \| null` | Thread ID used |
165166
| `suggestions` | `string[]` | Follow-up suggestions |
@@ -173,6 +174,7 @@ curl -X POST http://localhost:8000/api/v1/my_agent/invoke \
173174
```json
174175
{
175176
"response": "The capital of France is Paris.",
177+
"output": null,
176178
"agent_type": "my-agent",
177179
"thread_id": "thread-abc",
178180
"suggestions": ["Tell me about Paris landmarks"],

‎docs/architecture/overview.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -130,11 +130,14 @@ platform = AgentPlatform.from_folder(
130130
"agents/",
131131
store=SQLAlchemyStore("postgresql+asyncpg://..."),
132132
enable_studio=True,
133-
enable_chainlit=True,
134133
)
135-
app = platform.app # FastAPI application
134+
app = platform.build() # FastAPI application
136135
```
137136

137+
Mount the optional Chainlit debugging UI with `agentomatic run --with-ui`
138+
(after installing `agentomatic[ui]`); it is not an `AgentPlatform` constructor
139+
option.
140+
138141
### AgentRegistry
139142

140143
An in-memory registry holding `RegisteredAgent` instances. Each agent carries:
@@ -375,7 +378,7 @@ from agentomatic import AgentPlatform
375378
from agentomatic.storage import MemoryStore
376379

377380
platform = AgentPlatform.from_folder("agents/", store=MemoryStore())
378-
app = platform.app
381+
app = platform.build()
379382

380383
# uvicorn main:app --reload --port 8000
381384
```

‎docs/getting-started/concepts.md‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -139,9 +139,9 @@ dialogue.
139139
```python
140140
# Client-side: continue a conversation
141141
response = client.post(
142-
"/agents/search_bot/chat",
142+
"/api/v1/search_bot/chat",
143143
json={
144-
"message": "Tell me more about that last point.",
144+
"content": "Tell me more about that last point.",
145145
"thread_id": "abc-123", # ← same thread
146146
},
147147
)
@@ -182,7 +182,7 @@ flowchart LR
182182
C -- yes --> D["Class-Based\nBaseGraphAgent"]
183183
C -- no --> E{"__init__.py?"}
184184
E -- yes --> F["Functional\nmanifest + graph_fn"]
185-
D --> G["Register\n26 REST Endpoints"]
185+
D --> G["Register\nagent route surface"]
186186
F --> G
187187
188188
style G fill:#e3f2fd,stroke:#1565c0
@@ -211,13 +211,13 @@ See [Agentomatic Studio](../guide/studio.md) for the full guide.
211211

212212
### :material-api: Endpoint
213213

214-
One of the **26 auto-generated REST API routes** per agent. Every registered
215-
agent automatically receives endpoints for:
214+
One of the **auto-generated REST API routes** per agent. Every registered
215+
agent automatically receives a route surface that includes:
216216

217217
| Category | Example Routes |
218218
|----------|---------------|
219219
| **Execution** | `/invoke`, `/stream`, `/batch` |
220-
| **Chat** | `/chat`, `/chat/stream` |
220+
| **Chat** | `/chat` |
221221
| **Threads** | `/threads`, `/threads/{id}/history` |
222222
| **Introspection** | `/config`, `/schema`, `/graph`, `/health` |
223223
| **Management** | `/feedback`, `/state`, `/metrics` |
@@ -294,7 +294,7 @@ sequenceDiagram
294294
participant A as Agent
295295
participant G as Graph Engine
296296
297-
C->>F: POST /agents/search_bot/invoke
297+
C->>F: POST /api/v1/search_bot/invoke
298298
F->>M: Auth · Rate Limit · CORS
299299
M->>R: Route to agent
300300
R->>A: agent.invoke(payload)
@@ -323,7 +323,8 @@ sequenceDiagram
323323
## ⚖️ Two Patterns: Class-Based vs Functional
324324

325325
Agentomatic supports **two ways** to define agents. Both are fully
326-
auto-discovered and receive the same 26 REST endpoints.
326+
auto-discovered and receive the same generated route surface (unless a custom
327+
router replaces it).
327328

328329
### Choosing a Pattern
329330

‎docs/getting-started/first-agent.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -217,7 +217,7 @@ Enable persistent chat by adding a storage backend:
217217
from agentomatic import AgentPlatform
218218
from agentomatic.storage import SQLAlchemyStore
219219

220-
store = SQLAlchemyStore("sqlite:///./data/agents.db")
220+
store = SQLAlchemyStore("sqlite+aiosqlite:///./data/agents.db")
221221

222222
platform = AgentPlatform.from_folder(
223223
"agents/",

‎docs/getting-started/quickstart.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -404,7 +404,7 @@ Interact with the running agent using any HTTP client:
404404
curl -X POST http://localhost:8000/api/v1/my_chatbot/chat \
405405
-H "Content-Type: application/json" \
406406
-d '{
407-
"query": "My name is Alice",
407+
"content": "My name is Alice",
408408
"thread_id": "thread_abc123",
409409
"user_id": "user-1"
410410
}'
@@ -413,7 +413,7 @@ Interact with the running agent using any HTTP client:
413413
curl -X POST http://localhost:8000/api/v1/my_chatbot/chat \
414414
-H "Content-Type: application/json" \
415415
-d '{
416-
"query": "What is my name?",
416+
"content": "What is my name?",
417417
"thread_id": "thread_abc123",
418418
"user_id": "user-1"
419419
}'

‎docs/guide/agent-structure.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ Agentomatic follows a **convention-over-configuration** model. Each agent lives
1313

1414
## 🎯 Choose Your Agent Pattern
1515

16-
Agentomatic supports **two patterns** for defining agents. Both are fully auto-discovered and get the same 26 REST endpoints.
16+
Agentomatic supports **two patterns** for defining agents. Both are fully
17+
auto-discovered and get the same generated route surface.
1718

1819
```mermaid
1920
flowchart TD
@@ -542,7 +543,8 @@ agent_tools = [calculate_salary, search_database]
542543

543544
### 6. `api.py` — Custom FastAPI Router
544545

545-
If `api.py` exports a `router`, **Agentomatic drops all 26 auto-generated endpoints** for this agent and mounts your custom router instead.
546+
If `api.py` exports a `router`, **Agentomatic drops the auto-generated routes**
547+
for this agent and mounts your custom router instead.
546548

547549
```python
548550
# agents/my_agent/api.py

‎docs/guide/debug-ui.md‎

Lines changed: 34 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# Chat Interface (Chainlit)
22

3-
Agentomatic includes a built-in ChatGPT-like conversational interface powered by **Chainlit**. It provides an interactive chat playground to test agent responses, compare prompt versions, inspect tool calls, and collect user feedback — without writing any frontend code.
3+
Agentomatic includes a built-in Chainlit **debug chat**. It lets an operator
4+
select a deployed agent, send a synchronous invoke request, and inspect the
5+
returned response, execution-step labels, citations, and suggestions — without
6+
writing a frontend.
47

58
!!! info "Chat UI vs Agentomatic Studio"
69
Agentomatic offers **two** debug interfaces for different workflows:
@@ -10,7 +13,7 @@ Agentomatic includes a built-in ChatGPT-like conversational interface powered by
1013
| **Purpose** | Conversational testing | Visual debugging & inspection |
1114
| **Launch flag** | `--with-ui` | `--studio` |
1215
| **URL** | `/chat` | `/studio/ui/` |
13-
| **Best for** | Testing agent responses, prompt A/B testing, user feedback | Graph visualization, state inspection, time-travel, breakpoints |
16+
| **Best for** | Quick local response checks | Graph visualization, state inspection, time-travel, breakpoints |
1417
| **Interface** | Chat bubbles (ChatGPT-like) | Node graph + debug panels |
1518
| **Framework** | Chainlit | React |
1619

@@ -30,7 +33,9 @@ pip install "agentomatic[ui]"
3033

3134
=== "Embedded Mode (Recommended)"
3235

33-
Mounts the Chainlit interface directly into your FastAPI application. API requests and chat sessions share the same persistence backend and middleware stack.
36+
Mounts the Chainlit interface into the FastAPI application. The debug chat
37+
invokes the platform's normal `/invoke` API, so that API request follows
38+
the platform middleware.
3439

3540
```bash
3641
agentomatic run --with-ui
@@ -71,69 +76,45 @@ pip install "agentomatic[ui]"
7176
agentomatic run --with-ui --reload
7277
```
7378

79+
!!! warning "Local debug surface, not an authenticated operator console"
80+
The bundled UI currently sends plain `/invoke` requests and does not
81+
forward an API key, JWT, browser identity, or a conversation `thread_id`.
82+
It is intended for a local or otherwise trusted debugging setup. For a
83+
production frontend, use the documented REST/Studio APIs and your own
84+
authentication and session handling.
85+
7486
---
7587

7688
## Interface Features
7789

7890
### :material-robot: Agent Selector
7991

80-
A top-navigation dropdown lists all registered agents discovered by the platform registry. Select an agent to dynamically load its input form, configuration, and documentation.
81-
82-
### :material-tag: Prompt Version Selector
83-
84-
Inspect and switch between prompt versions (e.g., `v1`, `v2`, `v1_formal`) on the fly. Chat queries execute against the selected version, enabling manual A/B comparison of prompt behaviors.
85-
86-
```json
87-
// agents/my_agent/prompts.json
88-
{
89-
"v1": {
90-
"system": "You are a concise assistant.",
91-
"user_template": "Query: {query}"
92-
},
93-
"v2": {
94-
"system": "You are a creative, detailed assistant.",
95-
"user_template": "Please elaborate on: {query}"
96-
}
97-
}
98-
```
99-
100-
### :material-waves: Token-by-Token Streaming
101-
102-
If your agent supports streaming (via SSE), response completions stream onto the screen in real-time, matching the experience of ChatGPT and similar interfaces.
103-
104-
### :material-hammer-wrench: Tool Call Visualizations
92+
A Chainlit settings selector lists agents returned by the platform registry.
93+
Select an agent to send subsequent messages to that agent's `/invoke` route.
10594

106-
Intermediate agent actions — tool calls, function invocations, retrieval steps — are captured and rendered as clean, expandable panels in the chat flow. Click a panel to inspect the exact input arguments and JSON output returned by the tool.
95+
### :material-hammer-wrench: Invocation inspection
10796

108-
### :material-brain: Chain-of-Thought & Reasoning
109-
110-
If your agent returns reasoning or step-by-step logs, the UI highlights these in collapsible cards showing the agent's thought process before the final answer.
97+
Each message creates an expandable Chainlit step containing the `/invoke`
98+
payload and complete JSON response. If the response contains `steps_taken`,
99+
the UI displays those agent-supplied execution labels in a second step. It does
100+
not stream `/invoke/stream`, inspect provider tool calls independently, or
101+
infer hidden chain-of-thought.
111102

112103
### :material-book-open-variant: Citations & Sources
113104

114-
Citations returned by RAG pipelines are rendered as clickable badges at the bottom of messages, referencing PDFs, web links, or documentation files.
115-
116-
### :material-thumb-up: User Feedback Collection
117-
118-
Every response includes thumbs-up and thumbs-down icons. Users can submit rating scores and commentary directly from the UI. Feedback is:
119-
120-
- Immediately saved to the platform's database (SQL or Memory)
121-
- Available via the `/api/v1/{agent}/feedback` endpoint
122-
- Exportable as training data for prompt optimization
123-
124-
!!! note "Feedback-driven optimization"
125-
Feedback collected through the Chat UI can be exported and used as evaluation datasets for the [Prompt Optimization](optimization.md) pipeline:
126-
```bash
127-
agentomatic optimize my_agent --dataset feedback_export.jsonl --metrics relevancy
128-
```
105+
Citations returned by the agent are displayed as an expandable JSON retrieval
106+
step. The bundled UI does not submit feedback; use the agent feedback API or a
107+
production client for that workflow.
129108

130109
---
131110

132111
## Customization
133112

134113
### Theme & Layout
135114

136-
When running `agentomatic run --with-ui` for the first time, Agentomatic generates a default `.chainlit/config.toml` file. Customize it to match your brand:
115+
Chainlit controls its own theme and layout files. If your project has a
116+
`.chainlit/config.toml`, customize it according to your installed Chainlit
117+
version; Agentomatic does not generate or manage that file.
137118

138119
```toml
139120
[theme]
@@ -151,7 +132,9 @@ default_expand_messages = true
151132

152133
### Custom Welcome Message
153134

154-
Edit the `.chainlit/README.md` file to customize the welcome screen shown when users open a new session:
135+
The bundled debug chat sends its welcome message from
136+
`agentomatic.ui.chat`; customize that module or provide a dedicated Chainlit
137+
application when you need branded copy and behavior.
155138

156139
```markdown
157140
# Welcome to My Agent Platform 🚀
@@ -194,8 +177,8 @@ mount(app) # Chat UI available at /chat
194177
| Scenario | Use Chat UI | Use Studio |
195178
|----------|:-----------:|:----------:|
196179
| Testing agent response quality | ✅ | |
197-
| Comparing prompt versions side-by-side | ✅ | |
198-
| Collecting user feedback | ✅ | |
180+
| Comparing prompt versions side-by-side | | ✅ (use a run payload) |
181+
| Collecting user feedback | | ✅ (use the agent feedback API) |
199182
| Demonstrating agents to stakeholders | ✅ | |
200183
| Debugging graph execution flow | | ✅ |
201184
| Inspecting intermediate node state | | ✅ |

‎docs/guide/delegation.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -163,8 +163,9 @@ from __future__ import annotations
163163

164164
from agentomatic.delegation import AgentDelegator
165165

166-
# Agents this coordinator is allowed to delegate to.
167-
# The ZeroTrustEnforcer blocks any delegation not in this list.
166+
# Targets for which this module creates handoff tools.
167+
# Pair this with an AgentSecurityPolicy when your orchestration code enforces
168+
# delegation authorization.
168169
DELEGATION_TARGETS = ["researcher", "writer"]
169170

170171

‎docs/guide/ingestion.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ exposes:
3636
|----------|-------------|
3737
| `POST /api/v1/ingestion/{name}/run` | Run synchronously, return the result |
3838
| `POST /api/v1/ingestion/{name}/run/async` | Submit as a background **task**, return a pollable id |
39+
| `POST /api/v1/ingestion/{name}/run/batch` | Fan out multiple inputs as one background task |
3940
| `GET /api/v1/ingestion/{name}/info` | Ingestor metadata + input schema |
4041
| `GET /api/v1/ingestion/{name}/health` | Readiness/health |
4142
| `GET /api/v1/ingestion` | List all ingestors (the resource router is mounted when an ingestor is discovered) |
@@ -202,9 +203,10 @@ emb = get_embeddings("openai", model="text-embedding-3-small")
202203
vectors = emb.embed_documents(["hello", "world"])
203204
```
204205

205-
Providers: `ollama`, `openai`, `hash` (deterministic, dependency-free — great
206-
for tests/offline), and `dummy`. Instances are cached per `(provider, kwargs)`,
207-
so requesting the same configuration returns the same object.
206+
Providers: `ollama`, `openai`, `azure_openai`, `hash` (deterministic,
207+
dependency-free — great for tests/offline), and `dummy`. Instances are cached
208+
per `(provider, kwargs)`, so requesting the same configuration returns the
209+
same object.
208210

209211
## Programmatic registration
210212

0 commit comments

Comments
 (0)