Part 2 · Python In-Process Embedding

The shortest integration path for Python hosts: from agentao import Agentao and drive the runtime with method calls — no protocol overhead.

Key terms in this Part

Five vocabulary items you'll see throughout — bookmark Appendix G for the full glossary.

• Agentao instance — one constructor call → one stateful session; close() is mandatory · §2.3, G.1
• Working directory (cwd) — file-tool root, MCP cwd, AGENTAO.md lookup; frozen at construction · §2.2, G.1
• Transport — push-style callback (emit(event)) for streaming UI · §2.7, G.2
• CancellationToken — host-side handle to abort an in-flight chat() · §2.6, G.1
• extra_mcp_servers — per-session MCP injection (different tenants → different tokens) · §2.2

Coverage

• 2.1 Install & Import — version pinning, extras, lazy loading
• 2.2 Constructor Reference — every parameter, working-directory freeze, session-scoped MCP, production template
• 2.3 Lifecycle — chat() / clear_history() / close(), runtime model swap, concurrency patterns, full FastAPI example
• 2.4 Session state — the four state buckets, persist/restore recipe, memory auto-restore
• 2.5 Runtime LLM switch — set_provider() / set_model(), routing patterns, fallback chain
• 2.6 Cancellation & timeouts — CancellationToken, disconnect wiring, hard timeouts, max_iterations
• 2.7 FastAPI / Flask embedding — production templates with SSE, session pool, auth, cancellation

Read by task

What you're doing now	Shortest path
Embed the Python SDK in a script	2.1 Install & Import → 2.2 Minimum constructor params → 2.3 Standard lifecycle
Wire it into a FastAPI / Flask product	2.7 Production template → 2.6 Cancellation & timeouts → 2.4 Session state
Build multi-tenant / multi-session pooling	2.2 Constructor params → 2.4 Session state → 2.7 Session-pool template
Look up a specific API	2.2 Constructor Reference or Appendix A · API Reference

Before you start

Make sure you've read:

• 1.2 Core Concepts — Agent / Tool / Transport / Working Directory vocabulary
• 1.3 Integration Modes — confirm Python SDK is the right pick
• 1.4 Hello Agentao — 20-line runnable skeleton

Mental model

An agent is not a function call — it is a stateful process component. One Agentao(...) == one session. Many sessions → many instances. close() is mandatory, not polite.

→ Start with 2.1 →