01-rw-r--r--46Lno-keyhello_world.pyNo API key needed. Runs entirely offline with the built-in LocalProvider.▾
$cat examples/01_hello_world.py
02-rw-r--r--69Lno-keysearch_weather.pyNo API key needed — runs with the built-in LocalProvider.▾
$cat examples/02_search_weather.py
03-rw-r--r--205Lno-keytoolbox.pyNo API key needed for exploring tool schemas.▾
$cat examples/03_toolbox.py
04-rw-r--r--89Lapi-keyconversation_memory.pyMulti-turn Conversation Memory with automatic context preservation▾
$cat examples/04_conversation_memory.py
05-rw-r--r--133Lapi-keycost_tracking.pyCost Tracking — token counting, cost estimation, and usage summaries▾
$cat examples/05_cost_tracking.py
06-rw-r--r--194Lapi-keyasync_agent.pyAsync Agent — arun(), concurrent agents, and FastAPI integration patterns▾
$cat examples/06_async_agent.py
07-rw-r--r--350Lno-keystreaming_tools.pyStreaming Tools — Generator-based progressive output for long-running operations▾
$cat examples/07_streaming_tools.py
08-rw-r--r--315Lapi-keystreaming_parallel.pyStreaming and Parallel Tool Execution — astream(), asyncio.gather, StreamChunk▾
$cat examples/08_streaming_parallel.py
09-rw-r--r--219Lapi-keycaching.pyResponse Caching — InMemoryCache (LRU+TTL) and RedisCache for avoiding redundant LLM calls▾
$cat examples/09_caching.py
100-rw-r--r--179Lapi-keydeferred_confirmation.pyThe built-in approval gate blocks the agent loop waiting for a "yes" — wrong for WhatsApp/Telegram/Slack agents, where the user's confirmation arrives as▾
$cat examples/100_deferred_confirmation.py
101-rw-r--r--108Lapi-keylitellm_provider.pyOffline-safe: the demo below injects a fake `litellm` module so it runs without litellm installed or any API key. A real call is shown at the end,▾
$cat examples/101_litellm_provider.py
102-rw-r--r--102Lno-keyrouter_provider.pyA RouterProvider wraps multiple providers organized cheapest -> priciest and routes each request to a tier based on a deterministic, rule-based▾
$cat examples/102_router_provider.py
103-rw-r--r--98Lno-keya2a_protocol.pyDemonstrates A2AServer + A2AClient: one selectools agent exposes itself over A2A (Agent Card discovery + JSON-RPC tasks) and another process▾
$cat examples/103_a2a_protocol.py
104-rw-r--r--78Lapi-keytoolbox_expansion.pyFully offline: the calculator runs locally and the Slack call is mocked. The API-backed tools (email, PDF, Slack, Notion, Linear) need their optional▾
$cat examples/104_toolbox_expansion.py
105-rw-r--r--107Lapi-keysession_search.pyDemonstrates the @beta `SessionStore.search()` method: an agent can "remember what we discussed last Tuesday" by querying message content▾
$cat examples/105_session_search.py
106-rw-r--r--91Lapi-keyunified_memory.pyUnifiedMemory orchestrates the four existing memory systems into one lifecycle: short-term (ConversationMemory rolling window), long-term▾
$cat examples/106_unified_memory.py
107-rw-r--r--129Lapi-keytool_result_compression.pyVerbose tool outputs (a web scrape returning 10KB of HTML, a SQL query dumping 500 rows) waste context window on every subsequent iteration. With▾
$cat examples/107_tool_result_compression.py
108-rw-r--r--147Lapi-keyagent_hitl.pyStandalone agents (no AgentGraph needed) can gate specific tools behind an approval handler:▾
$cat examples/108_agent_hitl.py
109-rw-r--r--119Lno-keyplanning_as_config.pyAdd planning to ANY Agent with a config flag — no PlanAndExecuteAgent wiring required. When `PlanningConfig.enabled=True` and the input looks▾
$cat examples/109_planning_as_config.py
10-rw-r--r--312Lapi-keyrouting_mode.pyRouting Mode — Agent selects a tool without executing it. Intent classification▾
$cat examples/10_routing_mode.py
110-rw-r--r--137Lapi-keyquick_reply_buttons.pyExample 100 covers FREE-TEXT confirmation ("sim", "yes") through the RegexConfirmParser. But chat channels with quick-reply buttons (Twilio▾
$cat examples/110_quick_reply_buttons.py
111-rw-r--r--84Lapi-keyknowledge_sanitizers.pyRemembered content flows back into the system prompt via build_context(), so the knowledge store is a prompt-injection vector: anything a user (or a▾
$cat examples/111_knowledge_sanitizers.py
11-rw-r--r--341Lapi-keytool_analytics.pyTool Usage Analytics — call counts, success rates, timing, cost attribution▾
$cat examples/11_tool_analytics.py
12-rw-r--r--300Lno-keyobservability_hooks.pyNOTE: For production observability (Langfuse, Datadog, OpenTelemetry), prefer the class-based AgentObserver protocol introduced in v0.14.0. It provides▾
$cat examples/12_observability_hooks.py
13-rw-r--r--220Lno-keydynamic_tools.pyDynamic Tools — ToolLoader, plugin directories, hot-reload, runtime tool management▾
$cat examples/13_dynamic_tools.py
14-rw-r--r--157Lapi-keyrag_basic.pyBasic RAG — document loading, chunking, embedding, vector search, and question answering▾
$cat examples/14_rag_basic.py
15-rw-r--r--339Lapi-keysemantic_search.pySemantic Search — pure embedding-based search with metadata filtering▾
$cat examples/15_semantic_search.py
16-rw-r--r--328Lapi-keyrag_advanced.pyAdvanced RAG — PDFs, SQLite persistent storage, custom chunking, metadata filtering▾
$cat examples/16_rag_advanced.py
17-rw-r--r--536Lapi-keyrag_multi_provider.pyOptional: ANTHROPIC_API_KEY, GOOGLE_API_KEY for cross-provider comparisons▾
$cat examples/17_rag_multi_provider.py
18-rw-r--r--270Lapi-keyhybrid_search.pyHybrid Search — BM25 keyword + vector semantic search with RRF/weighted fusion and reranking▾
$cat examples/18_hybrid_search.py
19-rw-r--r--224Lapi-keyadvanced_chunking.pyAdvanced Chunking — SemanticChunker (embedding-based) and ContextualChunker (LLM-enriched)▾
$cat examples/19_advanced_chunking.py
20-rw-r--r--547Lapi-keycustomer_support_bot.pyCustomer Support Bot — multi-tool workflow combining search, ticketing, and escalation▾
$cat examples/20_customer_support_bot.py
21-rw-r--r--820Lapi-keydata_analysis_agent.pyData Analysis Agent — data exploration, filtering, aggregation, and visualization tools▾
$cat examples/21_data_analysis_agent.py
22-rw-r--r--253Lapi-keyollama_local.pyOllama Local Model — run agents with fully local LLMs via Ollama. No cloud API needed▾
$cat examples/22_ollama_local.py
23-rw-r--r--243Lapi-keystructured_output.pyDemonstrates: 1. Pydantic BaseModel as response_format▾
$cat examples/23_structured_output.py
24-rw-r--r--246Lapi-keytraces_and_reasoning.pyDemonstrates: 1. result.trace with TraceStep timeline▾
$cat examples/24_traces_and_reasoning.py
25-rw-r--r--250Lapi-keyprovider_fallback.pyDemonstrates: 1. FallbackProvider with priority ordering▾
$cat examples/25_provider_fallback.py
26-rw-r--r--263Lapi-keybatch_processing.pyDemonstrates: 1. agent.batch() for sync concurrent processing▾
$cat examples/26_batch_processing.py
27-rw-r--r--308Lapi-keytool_policy.pyDemonstrates: 1. ToolPolicy with allow/review/deny rules▾
$cat examples/27_tool_policy.py
28-rw-r--r--363Lapi-keyagent_observer.pyDemonstrates: 1. Custom AgentObserver subclass with run_id/call_id correlation▾
$cat examples/28_agent_observer.py
29-rw-r--r--155Lno-keyguardrails.pyDemonstrates input and output guardrails for content validation, PII redaction, topic blocking, and format enforcement.▾
$cat examples/29_guardrails.py
30-rw-r--r--88Lno-keyaudit_logging.pyDemonstrates JSONL audit logging with privacy controls and daily file rotation.▾
$cat examples/30_audit_logging.py
31-rw-r--r--109Lapi-keytool_output_screening.pyDemonstrates prompt injection detection in tool outputs, both per-tool and global screening.▾
$cat examples/31_tool_output_screening.py
32-rw-r--r--128Lapi-keycoherence_checking.pyDemonstrates LLM-based intent verification that catches tool calls diverging from the user's original request (prompt injection defence).▾
$cat examples/32_coherence_checking.py
33-rw-r--r--71Lno-keypersistent_sessions.pyDemonstrates JsonFileSessionStore: the agent's conversation history is persisted to disk and restored when a new agent is created with the same session_id.▾
$cat examples/33_persistent_sessions.py
34-rw-r--r--70Lno-keysummarize_on_trim.pyWhen the conversation exceeds max_messages, the oldest messages are removed. With summarize_on_trim=True the agent asks an LLM to condense them into a▾
$cat examples/34_summarize_on_trim.py
35-rw-r--r--78Lno-keyentity_memory.pyEntityMemory merges entities into a deduplicated registry and builds a context block for the system prompt. This example manually feeds entities to demonstrate▾
$cat examples/35_entity_memory.py
36-rw-r--r--81Lno-keyknowledge_graph.pyKnowledgeGraphMemory stores subject-relation-object triples in a TripleStore. Relevant triples are queried each turn and injected into the system prompt.▾
$cat examples/36_knowledge_graph.py
37-rw-r--r--79Lno-keyknowledge_memory.pyKnowledgeMemory stores daily log entries and persistent facts in MEMORY.md. When configured on an agent, a ``remember`` tool is auto-registered and the▾
$cat examples/37_knowledge_memory.py
38-rw-r--r--139Lno-keyterminal_tools.pyDemonstrates how to stop the agent loop after a specific tool fires, without making another LLM call. Two mechanisms:▾
$cat examples/38_terminal_tools.py
39-rw-r--r--166Lno-keyeval_framework.py==================================== Evaluate your agent's accuracy, tool use, latency, cost, and safety▾
$cat examples/39_eval_framework.py
40-rw-r--r--188Lno-keyeval_advanced.py====================================================================== Showcases advanced eval features:▾
$cat examples/40_eval_advanced.py
41-rw-r--r--127Lno-keymcp_client.py===================================================== Use tools from any MCP-compatible server in your selectools agent.▾
$cat examples/41_mcp_client.py
42-rw-r--r--80Lapi-keymcp_server.py======================================================== Turn any selectools @tool function into an MCP-compliant server.▾
$cat examples/42_mcp_server.py
43-rw-r--r--165Lapi-keytoken_budget.pyDemonstrates: - max_total_tokens: hard limit on cumulative tokens▾
$cat examples/43_token_budget.py
44-rw-r--r--203Lapi-keycancellation.pyDemonstrates: - CancellationToken for cooperative cancellation▾
$cat examples/44_cancellation.py
45-rw-r--r--212Lapi-keyapproval_gate.pyDemonstrates: - @tool(requires_approval=True) decorator flag▾
$cat examples/45_approval_gate.py
46-rw-r--r--178Lapi-keysimple_observer.pyDemonstrates: - SimpleStepObserver routes 31 events to one function▾
$cat examples/46_simple_observer.py
47-rw-r--r--136Lapi-keytoken_estimation.pyDemonstrates: - estimate_tokens() for single strings▾
$cat examples/47_token_estimation.py
48-rw-r--r--202Lapi-keymodel_switching.pyDemonstrates: - model_selector callback on AgentConfig▾
$cat examples/48_model_switching.py
49-rw-r--r--188Lapi-keyknowledge_stores.pyDemonstrates: - KnowledgeMemory with SQLiteKnowledgeStore backend▾
$cat examples/49_knowledge_stores.py
50-rw-r--r--132Lapi-keyreasoning_strategies.pyDemonstrates: - reasoning_strategy="react" — Thought → Action → Observation cycle▾
$cat examples/50_reasoning_strategies.py
51-rw-r--r--93Lapi-keytool_result_caching.pyDemonstrates: - @tool(cacheable=True) — cache tool results by name + args▾
$cat examples/51_tool_result_caching.py
52-rw-r--r--204Lapi-keysemantic_cache.pyDemonstrates: - SemanticCache as a drop-in replacement for InMemoryCache▾
$cat examples/52_semantic_cache.py
53-rw-r--r--264Lapi-keyprompt_compression.pyDemonstrates: - compress_context=True — enable proactive context compression▾
$cat examples/53_prompt_compression.py
54-rw-r--r--203Lapi-keyconversation_branching.pyDemonstrates: - ConversationMemory.branch() — snapshot memory for safe experimentation▾
$cat examples/54_conversation_branching.py
55-rw-r--r--64Lno-keyagent_graph_linear.pyDemonstrates a simple 3-node linear graph: planner → writer → reviewer → END▾
$cat examples/55_agent_graph_linear.py
56-rw-r--r--66Lno-keyagent_graph_parallel.pyDemonstrates parallel execution of multiple agents with state merging: entry → [researcher_a, researcher_b, researcher_c] → summarizer → END▾
$cat examples/56_agent_graph_parallel.py
57-rw-r--r--71Lno-keyagent_graph_conditional.pyDemonstrates conditional edges with path_map validation: drafter → router → (revise | publish) → END▾
$cat examples/57_agent_graph_conditional.py
58-rw-r--r--109Lno-keyagent_graph_hitl.pyDemonstrates generator nodes with yield InterruptRequest: - Graph pauses at reviewer node▾
$cat examples/58_agent_graph_hitl.py
59-rw-r--r--107Lno-keyagent_graph_checkpointing.pyDemonstrates durable mid-graph persistence using FileCheckpointStore: - Save checkpoints after each node▾
$cat examples/59_agent_graph_checkpointing.py
60-rw-r--r--124Lno-keysupervisor_agent.pyDemonstrates all four supervisor strategies: - plan_and_execute: LLM generates a plan, then executes each step▾
$cat examples/60_supervisor_agent.py
61-rw-r--r--84Lno-keyagent_graph_subgraph.pyDemonstrates SubgraphNode — an AgentGraph embedded as a node in another graph. Uses input_map and output_map for explicit state key translation.▾
$cat examples/61_agent_graph_subgraph.py
62-rw-r--r--101Lno-keyyaml_config.pyDemonstrates the structured AgentConfig workflow (v0.19.0): - Write a YAML config file describing the agent▾
$cat examples/62_yaml_config.py
63-rw-r--r--165Lno-keyagent_templates.pyDemonstrates the template system (v0.19.0): - List available built-in templates▾
$cat examples/63_agent_templates.py
64-rw-r--r--183Lno-keyselectools_serve.pyDemonstrates the `selectools serve` pattern (v0.19.0): - Create an agent with tools▾
$cat examples/64_selectools_serve.py
65-rw-r--r--122Lno-keytool_composition.pyDemonstrates composing multiple tools into a single composite tool (v0.19.0): - Define individual tools with @tool()▾
$cat examples/65_tool_composition.py
66-rw-r--r--132Lapi-keystreaming_pipeline.pyDemonstrates pipeline streaming (v0.19.0): - Build a multi-step pipeline with @step▾
$cat examples/66_streaming_pipeline.py
67-rw-r--r--137Lapi-keytype_safe_pipeline.pyDemonstrates type-safe step contracts in pipelines (v0.19.0): - Steps infer input/output types from type hints▾
$cat examples/67_type_safe_pipeline.py
68-rw-r--r--158Lapi-keypostgres_checkpoints.pyDemonstrates using PostgreSQL as a checkpoint backend (v0.19.0): - Create a PostgresCheckpointStore with a connection string▾
$cat examples/68_postgres_checkpoints.py
69-rw-r--r--369Lno-keytrace_store.pyDemonstrates saving and querying agent traces (v0.19.0): - InMemoryTraceStore for development▾
$cat examples/69_trace_store.py
70-rw-r--r--107Lno-keyplan_and_execute.pyThe planner Agent generates a JSON execution plan. Executor agents handle each step in sequence. Results are aggregated into a final output.▾
$cat examples/70_plan_and_execute.py
71-rw-r--r--107Lno-keyreflective_agent.pyThe actor Agent produces an initial draft. The critic Agent evaluates it and provides feedback. The actor revises based on the critique. This cycle repeats▾
$cat examples/71_reflective_agent.py
72-rw-r--r--123Lno-keydebate_agent.pyMultiple agents argue opposing positions over max_rounds rounds. Each agent sees the prior round transcript so they can respond to each other. A judge▾
$cat examples/72_debate_agent.py
73-rw-r--r--199Lno-keyteam_lead_agent.pyThe lead Agent generates a subtask plan and delegates to team members. Three delegation strategies are demonstrated:▾
$cat examples/73_team_lead_agent.py
74-rw-r--r--66Lno-keytrace_to_html.pyRenders an AgentTrace as a standalone HTML waterfall timeline. No external dependencies — the output is a single self-contained HTML file.▾
$cat examples/74_trace_to_html.py
75-rw-r--r--112Lapi-keystability_markers.pyThe stability module provides three decorators for annotating the public API stability of any class or function.▾
$cat examples/75_stability_markers.py
76-rw-r--r--39Lapi-keyvisual_builder.pytopology in a browser, generate Python or YAML, copy or download. Start the builder with one command (no config file needed):▾
$cat examples/76_visual_builder.py
77-rw-r--r--49Lapi-keyfaiss_vector_store.pyNo API key needed. Uses FAISS (Facebook AI Similarity Search) for high-performance local vector search. Supports save/load to disk.▾
$cat examples/77_faiss_vector_store.py
78-rw-r--r--46Lapi-keyqdrant_vector_store.pyQdrant is a high-performance vector database with advanced filtering. This example shows the API pattern (requires a running Qdrant server).▾
$cat examples/78_qdrant_vector_store.py
79-rw-r--r--43Lapi-keypgvector_store.pyUse your existing PostgreSQL database for vector similarity search. No additional database infrastructure needed.▾
$cat examples/79_pgvector_store.py
80-rw-r--r--76Lapi-keydocument_loaders.pyNo API key needed. Demonstrates all new document loader methods.▾
$cat examples/80_document_loaders.py
81-rw-r--r--57Lapi-keymultimodal_messages.pyNo API key needed for this demo. Shows how to create messages with images for vision-enabled models (GPT-4o, Claude 3.5, Gemini).▾
$cat examples/81_multimodal_messages.py
82-rw-r--r--64Lapi-keycode_execution.pyNo API key needed. Demonstrates the execute_python and execute_shell tools. WARNING: These tools execute code on your local machine. Do not use with▾
$cat examples/82_code_execution.py
83-rw-r--r--52Lapi-keyweb_search.pyNo API key needed. Uses DuckDuckGo for search (no rate limits for moderate use).▾
$cat examples/83_web_search.py
84-rw-r--r--53Lapi-keygithub_tools.pyNo API key needed (optional GITHUB_TOKEN increases rate limit from 60 to 5000/hr). Read-only operations only.▾
$cat examples/84_github_tools.py
85-rw-r--r--88Lapi-keydatabase_query.pyNo API key needed. Creates a sample SQLite database and queries it. Also supports PostgreSQL with psycopg2.▾
$cat examples/85_database_query.py
86-rw-r--r--52Lapi-keyazure_openai.pyRequires: AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_API_KEY env vars.▾
$cat examples/86_azure_openai.py
87-rw-r--r--56Lapi-keyotel_observer.pyMaps selectools observer events to OTel GenAI semantic convention spans. Works with any OTel-compatible backend.▾
$cat examples/87_otel_observer.py
88-rw-r--r--59Lapi-keylangfuse_observer.pyLangfuse is the most popular open-source LLM observability platform. Traces include LLM calls, tool executions, costs, and latencies.▾
$cat examples/88_langfuse_observer.py
89-rw-r--r--57Lno-keytyped_tool_parameters.pySince v0.22.0 (BUG-29), selectools emits proper JSON schema for typed collections. OpenAI strict mode requires `items` / `additionalProperties`▾
$cat examples/89_typed_tool_parameters.py
90-rw-r--r--64Lno-keyfallback_extended_retries.pySince v0.22.0 (BUG-27), selectools recognizes these transient errors: - 529 Anthropic Overloaded (very common on US-West traffic)▾
$cat examples/90_fallback_extended_retries.py
91-rw-r--r--60Lno-keystructured_retry_budget.pySince v0.22.0 (BUG-34), `max_iterations` controls tool-execution iterations and `RetryConfig.max_retries` controls structured-validation retries. They no▾
$cat examples/91_structured_retry_budget.py
92-rw-r--r--64Lapi-keysafe_parallel_pipeline.pySince v0.22.0 (BUG-30), `parallel()` branches each receive a deep copy of the input. Mutations in one branch do NOT affect siblings — even under▾
$cat examples/92_safe_parallel_pipeline.py
93-rw-r--r--81Lapi-keymulti_tenant_rag.pySince v0.22.0 (BUG-25), in-memory and BM25 stores raise NotImplementedError when you pass operator-syntax filters ({$in: [...]}) instead of silently▾
$cat examples/93_multi_tenant_rag.py
94-rw-r--r--50Lapi-keyazure_model_family.pySince v0.22.0 (BUG-28), AzureOpenAIProvider accepts a `model_family` parameter so deployments with custom names (e.g., "prod-chat") still use the correct▾
$cat examples/94_azure_model_family.py
95-rw-r--r--108Lapi-keyloop_detection.pySince v0.22.0, `AgentConfig.loop_detector` enables three composable detectors: - RepeatDetector: same (tool, args) N times in a row▾
$cat examples/95_loop_detection.py
96-rw-r--r--188Lno-keysupabase_session_store.pyDemonstrates SupabaseSessionStore: ConversationMemory persisted to a Supabase Postgres table as JSONB, with idempotent upserts and optional namespace▾
$cat examples/96_supabase_session_store.py
97-rw-r--r--126Lno-keyagent_as_api.pyDemonstrates AgentAPI: one line turns an Agent (or several) into a production-ready Starlette ASGI app with standardized JSON schemas,▾
$cat examples/97_agent_as_api.py
98-rw-r--r--123Lapi-keyknowledge_backend.pyDemonstrates the KnowledgeBackend protocol: KnowledgeMemory keeps using a fast local directory as scratch space, while a backend (Supabase or Redis)▾
$cat examples/98_knowledge_backend.py
99-rw-r--r--138Lapi-keytool_results_artifacts.pyTwo conventions every tool-using agent otherwise re-invents: 1. ToolResult — frozen dataclass base for typed tool returns. Subclasses set▾
$cat examples/99_tool_results_artifacts.py