Skip to content

Commit 2e6e8da

Browse files
ArnavBalyanArnavBalyan
authored
(#56) v0.9 Update docs to support Concierge FE modes
(#56) v0.9 Update docs to support Concierge FE modes
2 parents 06d62f7 + 3658fd4 commit 2e6e8da

6 files changed

Lines changed: 307 additions & 1 deletion

File tree

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,9 @@ dmypy.json
113113
# Pyre type checker
114114
.pyre/
115115

116+
# Claude Code
117+
.claude/
118+
116119
# IDE
117120
.vscode/
118121
.idea/

‎docs/logo-dark.svg‎

Lines changed: 38 additions & 0 deletions
Loading

‎docs/logo.svg‎

Lines changed: 38 additions & 0 deletions
Loading

‎docs/mint.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
{
22
"$schema": "https://mintlify.com/schema.json",
33
"name": "Concierge",
4+
"logo": {
5+
"light": "/logo.svg",
6+
"dark": "/logo-dark.svg"
7+
},
8+
"favicon": "/logo.svg",
49
"colors": {
510
"primary": "#8B5CF6",
611
"light": "#A78BFA",
@@ -15,7 +20,7 @@
1520
"navigation": [
1621
{
1722
"group": "Documentation",
18-
"pages": ["introduction"]
23+
"pages": ["introduction", "modes", "staged-workflows"]
1924
}
2025
],
2126
"footerSocials": {

‎docs/modes.mdx‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: Provider Modes
3+
description: "Control how tools are exposed to AI agents"
4+
---
5+
6+
Concierge wraps your tools through a **provider mode** that controls what the agent sees. Four modes, each a different trade-off between simplicity and structure.
7+
8+
## Plain
9+
10+
Default. All tools exposed directly — no wrapping, no transformation.
11+
12+
```python
13+
from concierge import Concierge
14+
15+
app = Concierge("my-server")
16+
```
17+
18+
The agent sees every tool you register and calls them by name. Use this for small APIs where all tools are relevant at once.
19+
20+
## Search
21+
22+
Two meta-tools: `search_tools(query)` and `call_tool(tool_name, arguments)`. The agent discovers tools via semantic search, then calls them by name.
23+
24+
```python
25+
from concierge import Concierge, Config, ProviderType
26+
27+
app = Concierge(
28+
"my-server",
29+
config=Config(provider_type=ProviderType.SEARCH),
30+
)
31+
```
32+
33+
Uses `sentence-transformers` for embeddings (install separately). Designed for large APIs with 100+ tools where the agent shouldn't see everything at once.
34+
35+
**Config options:**
36+
- `max_results` — number of search results returned (default: `5`)
37+
- `model` — custom `SentenceTransformer` instance (default: `BAAI/bge-large-en-v1.5`)
38+
39+
## Plan
40+
41+
One meta-tool: `execute_plan(steps)`. The agent submits a JSON plan — a list of sequential steps that can reference each other's outputs.
42+
43+
```python
44+
from concierge import Concierge, Config, ProviderType
45+
46+
app = Concierge(
47+
"my-server",
48+
config=Config(provider_type=ProviderType.PLAN),
49+
)
50+
```
51+
52+
**What the agent sends:**
53+
54+
```json
55+
{
56+
"steps": [
57+
{"id": "backup", "tool": "create_backup", "args": {"database": "prod"}},
58+
{
59+
"id": "validate",
60+
"tool": "validate_backup",
61+
"args": {
62+
"backup_id": {"output_by_reference": {"backup": ["backup_id"]}}
63+
}
64+
}
65+
]
66+
}
67+
```
68+
69+
Steps execute sequentially. A step can pass data to later steps using `output_by_reference` — but only into parameters annotated with `Sharable()`:
70+
71+
```python
72+
from typing import Annotated
73+
from concierge.core.sharable import Sharable
74+
75+
@app.tool()
76+
def validate_backup(backup_id: Annotated[str, Sharable()]) -> dict:
77+
...
78+
```
79+
80+
The reference `{"output_by_reference": {"backup": ["backup_id"]}}` resolves to `results["backup"]["backup_id"]`. Only backward references allowed — no cycles, no self-references.
81+
82+
## Code
83+
84+
One meta-tool: `execute_code(code, timeout)`. The agent writes async Python that calls tools directly.
85+
86+
```python
87+
from concierge import Concierge, Config, ProviderType
88+
89+
app = Concierge(
90+
"my-server",
91+
config=Config(provider_type=ProviderType.CODE),
92+
)
93+
```
94+
95+
**What the agent writes:**
96+
97+
```python
98+
# Discovery
99+
print(runtime.list_tools())
100+
print(runtime.get_tool_info("create_backup"))
101+
print(runtime.search_tools("backup"))
102+
103+
# Call tools
104+
backup = await tools.create_backup(database="prod")
105+
result = await tools.validate_backup(backup_id=backup["backup_id"])
106+
print(result)
107+
```
108+
109+
Two modules are injected into the sandbox:
110+
- `tools` — every registered tool as an async callable
111+
- `runtime` — discovery helpers: `list_tools()`, `get_tool_info(name)`, `search_tools(query)`
112+
113+
The sandbox restricts imports, `eval`, `exec`, `open`, and other unsafe builtins. Default timeout is 30 seconds.
114+
115+
## Comparison
116+
117+
| Mode | Agent sees | Best for |
118+
|------|-----------|----------|
119+
| Plain | All tools directly | Small APIs (<20 tools) |
120+
| Search | `search_tools` + `call_tool` | Large APIs (100+ tools) |
121+
| Plan | `execute_plan` | Multi-step workflows with data dependencies |
122+
| Code | `execute_code` | Complex logic, iteration, conditionals |

‎docs/staged-workflows.mdx‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: Staged Workflows
3+
description: "Progressive tool disclosure via stages and transitions"
4+
---
5+
6+
Stages control **which tools the agent can see at each step** of a workflow. Instead of exposing everything at once, you define groups of tools and the legal paths between them.
7+
8+
This is orthogonal to [provider modes](/modes) — stages work with any mode.
9+
10+
## Defining Stages
11+
12+
Map stage names to tool lists:
13+
14+
```python
15+
app.stages = {
16+
"preflight": ["preflight_check"],
17+
"drain": ["drain_connections"],
18+
"backup": ["create_backup", "validate_backup"],
19+
"migrate": ["apply_migration"],
20+
"verify": ["run_smoke_tests"],
21+
"release": ["undrain_connections", "notify_stakeholders"],
22+
"finalize": ["finalize_migration"],
23+
}
24+
```
25+
26+
The first stage defined is the default. When a session starts, the agent only sees tools from that stage.
27+
28+
## Defining Transitions
29+
30+
Map each stage to its allowed next stages:
31+
32+
```python
33+
app.transitions = {
34+
"preflight": ["drain"],
35+
"drain": ["backup"],
36+
"backup": ["migrate"],
37+
"migrate": ["verify"],
38+
"verify": ["release"],
39+
"release": ["finalize"],
40+
"finalize": [],
41+
}
42+
```
43+
44+
An empty list means the stage is terminal — no further transitions.
45+
46+
## Auto-Generated Tools
47+
48+
When stages are defined, Concierge adds two tools automatically:
49+
50+
- **`proceed_to_next_stage(target_stage)`** — moves to a new stage. Only accepts stages listed in the current stage's transitions. Triggers a tool list refresh so the agent sees the new stage's tools.
51+
- **`terminate_session()`** — clears all session state and resets to the initial stage.
52+
53+
## State
54+
55+
Per-session key-value storage, available in any tool:
56+
57+
```python
58+
@app.tool()
59+
def add_to_cart(product_id: str) -> dict:
60+
cart = app.get_state("cart", [])
61+
cart.append(product_id)
62+
app.set_state("cart", cart)
63+
return {"cart": cart}
64+
```
65+
66+
State persists across stage transitions within a session. Cleared on `terminate_session()`.
67+
68+
**State backends:**
69+
- **In-memory** (default) — single-process, no persistence
70+
- **Postgres** — distributed, persistent. Set `CONCIERGE_STATE_URL=postgresql://user:pass@host/db`
71+
72+
## Session Flow
73+
74+
```
75+
Session starts → agent sees "preflight" tools + proceed_to_next_stage
76+
→ agent calls preflight_check
77+
→ agent calls proceed_to_next_stage("drain")
78+
→ tool list refreshes → agent sees "drain" tools
79+
→ ...
80+
→ agent reaches terminal stage ("finalize")
81+
→ agent calls terminate_session → session resets
82+
```
83+
84+
## Combining with Provider Modes
85+
86+
Stages wrap whatever the provider mode exposes. For example, with `ProviderType.PLAN`, the agent sees `execute_plan` but it can only reference tools available in the current stage.
87+
88+
```python
89+
from concierge import Concierge, Config, ProviderType
90+
91+
app = Concierge(
92+
"my-server",
93+
config=Config(provider_type=ProviderType.PLAN),
94+
)
95+
96+
# register tools...
97+
98+
app.stages = {"browse": ["search"], "checkout": ["pay"]}
99+
app.transitions = {"browse": ["checkout"], "checkout": []}
100+
```

0 commit comments

Comments
 (0)