Skip to content

Commit e0f1126

Browse files
arpan404arpan404
committed
docs: make docs better
1 parent 4cb0282 commit e0f1126

34 files changed

Lines changed: 1531 additions & 256 deletions

‎cookbooks/simple-greeting-agent/main.py‎

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,16 @@
1-
import asyncio
21
from afk.agents import Agent
32
from afk.core import Runner
43

5-
agent = Agent(name="tutor", model="ollama_chat/gpt-oss:20b", instructions="You are a Python tutor.")
4+
agent = Agent(
5+
name="ticket-classifier",
6+
model="ollama_chat/gpt-oss:20b",
7+
instructions="""
8+
Read the support ticket and classify it as exactly one of:
9+
billing, technical, account, or other.
10+
Output only the category name.
11+
""",
12+
)
613

7-
async def main():
8-
runner = Runner()
9-
thread = "session-42"
10-
11-
r1 = await runner.run(agent, user_message="What are generators?", thread_id=thread)
12-
print(r1.final_text)
13-
14-
# Turn 2 — the agent remembers Turn 1
15-
r2 = await runner.run(agent, user_message="Show me an example", thread_id=thread)
16-
print(r2.final_text)
17-
18-
asyncio.run(main())
14+
runner = Runner()
15+
result = runner.run_sync(agent, user_message="I can't log into my account")
16+
print(result.final_text) # "account"

‎docs/docs.json‎

Lines changed: 96 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"logo": {
55
"light": "/logo-light.svg",
66
"dark": "/logo-dark.svg",
7-
"href": "https://github.com/socioy/afk"
7+
"href": "https://github.com/arpan404/afk"
88
},
99
"theme": "mint",
1010
"layout": "sidenav",
@@ -14,7 +14,7 @@
1414
},
1515
"topbarCtaButton": {
1616
"type": "github",
17-
"url": "https://github.com/socioy/afk"
17+
"url": "https://github.com/arpan404/afk"
1818
},
1919
"sidebar": {
2020
"items": "undecorated"
@@ -27,78 +27,90 @@
2727
},
2828
"footer": {
2929
"socials": {
30-
"github": "https://github.com/socioy/afk"
30+
"github": "https://github.com/arpan404/afk"
3131
}
3232
},
33+
"tabs": [
34+
{
35+
"name": "Examples",
36+
"url": "library/examples"
37+
}
38+
],
3339
"navigation": {
34-
"groups": [
35-
{
36-
"group": "Welcome",
37-
"pages": ["index", "library/overview", "library/quickstart"]
38-
},
39-
{
40-
"group": "Learn",
41-
"pages": [
42-
"library/learn-in-15-minutes",
43-
"library/mental-model",
44-
"library/how-to-use-afk"
45-
]
46-
},
47-
{
48-
"group": "Core Concepts",
49-
"pages": [
50-
"library/agents",
51-
"library/core-runner",
52-
"library/tools",
53-
"library/streaming",
54-
"library/memory",
55-
"library/system-prompts",
56-
"library/agent-skills"
57-
]
58-
},
59-
{
60-
"group": "Scaling Up",
61-
"pages": [
62-
"library/agentic-behavior",
63-
"library/agentic-levels",
64-
"library/architecture",
65-
"library/building-with-ai",
66-
"library/developer-guide"
67-
]
68-
},
40+
"tabs": [
6941
{
70-
"group": "Communication",
71-
"pages": [
72-
"library/messaging",
73-
"library/a2a",
74-
"library/task-queues",
75-
"library/mcp-server"
76-
]
77-
},
78-
{
79-
"group": "LLM Layer",
80-
"pages": [
81-
"llms/index",
82-
"llms/contracts",
83-
"llms/adapters",
84-
"llms/control-and-session",
85-
"llms/agent-integration"
42+
"tab": "Guides",
43+
"groups": [
44+
{
45+
"group": "Welcome",
46+
"pages": ["index", "library/overview", "library/quickstart"]
47+
},
48+
{
49+
"group": "Learn",
50+
"pages": [
51+
"library/learn-in-15-minutes",
52+
"library/mental-model",
53+
"library/how-to-use-afk"
54+
]
55+
},
56+
{
57+
"group": "Core Concepts",
58+
"pages": [
59+
"library/agents",
60+
"library/core-runner",
61+
"library/tools",
62+
"library/streaming",
63+
"library/memory",
64+
"library/system-prompts",
65+
"library/agent-skills"
66+
]
67+
},
68+
{
69+
"group": "Scaling Up",
70+
"pages": [
71+
"library/agentic-behavior",
72+
"library/agentic-levels",
73+
"library/architecture",
74+
"library/building-with-ai",
75+
"library/developer-guide"
76+
]
77+
},
78+
{
79+
"group": "Communication",
80+
"pages": [
81+
"library/messaging",
82+
"library/a2a",
83+
"library/task-queues",
84+
"library/mcp-server"
85+
]
86+
},
87+
{
88+
"group": "LLM Layer",
89+
"pages": [
90+
"llms/index",
91+
"llms/contracts",
92+
"llms/adapters",
93+
"llms/control-and-session",
94+
"llms/agent-integration"
95+
]
96+
},
97+
{
98+
"group": "Reliability",
99+
"pages": [
100+
"library/observability",
101+
"library/evals",
102+
"library/security-model",
103+
"library/failure-policy-matrix"
104+
]
105+
}
86106
]
87107
},
88108
{
89-
"group": "Reliability",
90-
"pages": [
91-
"library/observability",
92-
"library/evals",
93-
"library/security-model",
94-
"library/failure-policy-matrix"
95-
]
96-
},
97-
{
98-
"group": "Reference",
109+
"tab": "References",
99110
"pages": [
100111
"library/api-reference",
101-
"library/examples/index",
112+
"library/configuration-reference",
113+
"library/environment-variables",
102114
"library/full-module-reference",
103115
"library/public-imports-and-function-improvement",
104116
"library/run-event-contract",
@@ -108,6 +120,25 @@
108120
"library/tool-call-lifecycle",
109121
"library/checkpoint-schema"
110122
]
123+
},
124+
{
125+
"tab": "Examples",
126+
"pages": [
127+
"library/examples/index",
128+
"library/snippets/01_minimal_chat_agent",
129+
"library/snippets/02_policy_with_hitl",
130+
"library/snippets/03_subagents_with_router",
131+
"library/snippets/04_resume_and_compact",
132+
"library/snippets/05_direct_llm_structured_output",
133+
"library/snippets/06_tool_registry_security",
134+
"library/snippets/07_tool_hooks_and_middleware",
135+
"library/snippets/08_prebuilt_runtime_tools",
136+
"library/snippets/09_system_prompt_loader",
137+
"library/snippets/10_streaming_chat_with_memory",
138+
"library/snippets/11_cost_monitoring",
139+
"library/snippets/12_mcp_client_integration",
140+
"library/snippets/13_multi_model_fallback"
141+
]
111142
}
112143
]
113144
}

‎docs/index.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,12 +54,14 @@ print(result.state) # ← "completed"
5454

5555
```python
5656
from pydantic import BaseModel
57+
from afk.agents import Agent
5758
from afk.tools import tool
59+
from afk.core import Runner
5860

5961
class WeatherArgs(BaseModel):
6062
city: str
6163

62-
@tool(name="get_weather", description="Get current weather for a city.")
64+
@tool(args_model=WeatherArgs, name="get_weather", description="Get current weather for a city.")
6365
def get_weather(args: WeatherArgs) -> dict:
6466
return {"city": args.city, "temp_f": 72, "condition": "sunny"}
6567

@@ -70,6 +72,7 @@ agent = Agent(
7072
tools=[get_weather], # ← Attach tools here
7173
)
7274

75+
runner = Runner()
7376
result = runner.run_sync(agent, user_message="What's the weather in Austin?")
7477
print(result.final_text) # ← "It's 72°F and sunny in Austin."
7578
```

‎docs/library/a2a.mdx‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -73,16 +73,25 @@ flowchart LR
7373

7474
<Tabs>
7575
<Tab title="Request">
76-
```python class AgentInvocationRequest(BaseModel): target_agent: str # Which
77-
agent to invoke user_message: str # The input message context: dict = {} #
78-
Additional context idempotency_key: str # Deduplication key timeout_s: float
79-
= 60.0 # Max wait time thread_id: str | None = None # For multi-turn ```
76+
```python
77+
class AgentInvocationRequest(BaseModel):
78+
target_agent: str # Which agent to invoke
79+
user_message: str # The input message
80+
context: dict = {} # Additional context
81+
idempotency_key: str # Deduplication key
82+
timeout_s: float = 60.0 # Max wait time
83+
thread_id: str | None = None # For multi-turn
84+
```
8085
</Tab>
8186
<Tab title="Response">
82-
```python class AgentInvocationResponse(BaseModel): final_text: str #
83-
Agent's response state: str # completed, failed, degraded run_id: str #
84-
Unique run identifier error: str | None = None # Error details (if failed)
85-
usage: UsageAggregate | None # Token usage ```
87+
```python
88+
class AgentInvocationResponse(BaseModel):
89+
final_text: str # Agent's response
90+
state: str # completed, failed, degraded
91+
run_id: str # Unique run identifier
92+
error: str | None = None # Error details (if failed)
93+
usage: UsageAggregate | None # Token usage
94+
```
8695
</Tab>
8796
</Tabs>
8897

‎docs/library/agentic-levels.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ AFK applications progress through five levels of capability. Each level adds fea
2828
Add typed tool functions for the agent to call.
2929

3030
```python
31-
@tool(name="search", description="Search knowledge base.")
31+
@tool(args_model=SearchArgs, name="search", description="Search knowledge base.")
3232
def search(args: SearchArgs) -> dict: ...
3333

3434
agent = Agent(name="helper", model="gpt-4.1-mini", tools=[search])
@@ -48,8 +48,8 @@ AFK applications progress through five levels of capability. Each level adds fea
4848
```python
4949
coordinator = Agent(
5050
name="coordinator",
51+
model="gpt-4.1-mini",
5152
subagents=[researcher, writer, reviewer],
52-
join_policy="all_required",
5353
)
5454
```
5555

‎docs/library/agents.mdx‎

Lines changed: 14 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -21,17 +21,17 @@ That's it. Three fields define a working agent. Everything else is optional.
2121

2222
## Agent fields reference
2323

24-
| Field | Type | Default | Purpose |
25-
| ------------------ | -------------------- | -------- | ----------------------------------------------------------------- |
26-
| `name` | `str` | required | Agent identity for logs, telemetry, and subagent routing |
27-
| `model` | `str` or `LLMClient` | required | LLM model name or pre-built client instance |
28-
| `instructions` | `str` | `""` | System prompt — what the agent knows and how it behaves |
29-
| `instruction_file` | `str` | `None` | Path to a `.txt` or `.md` file containing the system prompt |
30-
| `tools` | `list[tool]` | `[]` | Typed functions the agent can call |
31-
| `subagents` | `list[Agent]` | `[]` | Specialist agents this agent can delegate to |
32-
| `fail_safe` | `FailSafeConfig` | defaults | Step limits, cost budgets, timeout, and failure policies |
33-
| `context` | `dict` | `{}` | Key-value context available in prompt templates and tool handlers |
34-
| `model_resolver` | `callable` | `None` | Custom function to resolve model names to LLM clients |
24+
| Field | Type | Default | Purpose |
25+
| ------------------ | -------------------- | -------- | --------------------------------------------------------------- |
26+
| `name` | `str` | required | Agent identity for logs, telemetry, and subagent routing |
27+
| `model` | `str` or `LLMClient` | required | LLM model name or pre-built client instance |
28+
| `instructions` | `str` | `""` | System prompt — what the agent knows and how it behaves |
29+
| `instruction_file` | `str` | `None` | Path to a `.txt` or `.md` file containing the system prompt |
30+
| `tools` | `list[tool]` | `[]` | Typed functions the agent can call |
31+
| `subagents` | `list[Agent]` | `[]` | Specialist agents this agent can delegate to |
32+
| `fail_safe` | `FailSafeConfig` | defaults | Step limits, cost budgets, timeout, and failure policies |
33+
| `context_defaults` | `dict` | `{}` | Default JSON context merged into each run before caller context |
34+
| `model_resolver` | `callable` | `None` | Custom function to resolve model names to LLM clients |
3535

3636
## Single agent vs multi-agent
3737

@@ -131,9 +131,9 @@ agent = Agent(
131131
max_total_cost_usd=0.50, # Max estimated cost
132132

133133
# What to do when things fail
134-
llm_failure_policy="degrade", # "fail" | "degrade"
135-
tool_failure_policy="continue", # "fail" | "degrade" | "continue"
136-
subagent_failure_policy="degrade", # "fail" | "degrade" | "continue"
134+
llm_failure_policy="retry_then_degrade", # "retry_then_fail" | "retry_then_degrade" | "fail_fast"
135+
tool_failure_policy="continue_with_error", # "continue_with_error" | "retry_then_continue" | "fail_run"
136+
subagent_failure_policy="continue", # "continue" | "retry_then_fail" | "skip_action"
137137

138138
# Fallback model chain for LLM resilience
139139
fallback_model_chain=["gpt-4.1-mini", "gpt-4.1-nano"],

0 commit comments

Comments
 (0)