1.4 Hello Agentao in 5 min

Goal: get a minimal Python embedding running. Pure SDK path, no custom code.

Want a non-Python first taste? Jump to 3.1 ACP Quick Try instead.

⚡ Runnable end-to-end (≈ 3 minutes)

Outcome — agent thinks, runs glob + run_shell_command, prints the 3 largest files under cwd. Stack — pip install 'agentao>=0.5.0' + 3 env vars + 6 lines of Python. Run — python hello.py (after pasting the snippet from Step 3 below).

Step 1 · Install (1 minute)

pip install 'agentao>=0.5.0'

pip install agentao ships the embedding-only core. Add extras ([web], [cli], [i18n], …) later as needed — see 1.5 Requirements.

Step 2 · Configure credentials (1 minute)

export OPENAI_API_KEY="sk-..."
export OPENAI_BASE_URL="https://api.openai.com/v1"   # or any OpenAI-compatible endpoint
export OPENAI_MODEL="gpt-5.4"

All three are required. DeepSeek / Gemini / vLLM work the same way — just point OPENAI_BASE_URL and OPENAI_MODEL at them.

Step 3 · Run (1 minute)

Save as hello.py:

from pathlib import Path
from agentao.embedding import build_from_environment

agent = build_from_environment(working_directory=Path.cwd())
print(agent.chat("List the 3 largest files under the current directory."))
agent.close()

python hello.py

You'll see Agentao think, call run_shell_command / glob, and print a final answer like:

The three largest files under the current directory are:
1. ./node_modules/.cache/...   (12 MB)
2. ./dist/bundle.js            (4.1 MB)
3. ./README.md                 (38 KB)

What just happened

• build_from_environment(...) read the three variables from Step 2 and built an Agentao — one stateful session, with history, tools, and memory bound to this instance. It reads the environment, .env and .agentao/ files the way the CLI does; a direct Agentao(...) reads none of them and needs api_key=, base_url= and model= passed in (2.2)
• chat() ran the full LLM loop: think → call tool → observe → think → answer
• working_directory rooted file/shell tools at the current dir. Always pass an explicit Path in production so concurrent instances don't share Path.cwd()
• close() released MCP subprocesses and DB handles — wrap in try/finally in real code

Add streaming output (5 more lines)

from pathlib import Path
from agentao.embedding import build_from_environment
from agentao.transport import SdkTransport

def stream(ev):
    if ev.type.name == "LLM_TEXT":
        print(ev.data["chunk"], end="", flush=True)

agent = build_from_environment(
    working_directory=Path.cwd(),
    transport=SdkTransport(on_event=stream),
)
agent.chat("List the 3 largest files under the current directory.")
agent.close()

LLM_TEXT is an internal event whose fields may change between releases. In async code, the stable way to stream the text is agent.astream(...) — see 4.4.

That's the whole pattern. Tool confirmations, custom tools, permissions, memory — every other feature extends from these two calls (building the agent + chat(...)).

Troubleshooting

Symptom	Likely cause
ImportError: cannot import name 'Agentao'	Forgot pip install agentao, or imported from agentao.agent (not the public path)
ValueError: Agentao(): api_key, base_url, and model are required…	One of OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL is unset, or the agent was built with Agentao(...), which reads no environment variables — see Appendix F.1
Agent says Tool execution declined	Default permissions denied a write — see 5.4
chat() never returns	Likely tool loop or no ask_user callback — see Appendix F.2

Full FAQ: Appendix F.

Where to go next

If you want to…	Read
Wire one of your business APIs as a tool	5.1 Custom Tools
Embed in FastAPI / Flask with SSE streaming	2.7 FastAPI / Flask Embedding
Drive Agentao from Node / Go / Rust / IDE	Part 3 · ACP
Verify environment requirements first	1.5 Requirements
Understand the core nouns (Agent / Tool / Skill / …)	1.2 Core Concepts