How xpzero/demo-agent works
demo-agent is a learning project implementing a tool-using, streaming LLM agent with both CLI and browser chat. A user message enters either interface, reaches the agent loop, and may trigger locally executed tools before the model returns a final response. Conversations preserve Responses items across turns and sessions; permission checks and approval handling govern sensitive tool calls. The README documents the HTTP streaming boundary and major tool capabilities, but sampled source does not show the API, loop, or approval wiring in detail, so uncertain call edges are omitted.
Main entry points: __init__.py Tool registry · loop.py Agent loop · chat.py CLI chat · api.py HTTP API
Components 24
Chat interfaces
- Browser chat
web/src/App.tsx - Chat adapter
web/src/adapter.ts - CLI chat
server/cli/chat.py - HTTP API
server/api.py
Agent runtime
- Agent loop
server/agent/loop.py - OpenAI client
server/agent/client.py - Service container
server/services/container.py
Tools and permissions
- Tool registry
server/tools/__init__.py - Calculation
server/tools/calculate.py - Weather
server/tools/get_weather.py - File reading
server/tools/files/read.py - File writing
server/tools/files/write.py - Path checks
server/tools/files/paths.py - Web search
server/tools/web/search.py - URL fetch
server/tools/web/fetch.py - Permission service
server/services/permission/service.py - Permission rules
server/services/permission/rules.py - Approval handling
server/agent/approval.py
Conversation state
- Session manager
server/sessions/manager.py - Session model
server/sessions/session.py - Session files
server/sessions/manager.py
Other components
- User
- Tavily
- Responses API
Connections 27
- User → Browser chat: sends message
- Browser chat → Chat adapter: submits chat
- Chat adapter → HTTP API: streams requests
- HTTP API → Agent loop: runs agent
- User → CLI chat: enters prompt
- CLI chat → Agent loop: runs agent
- CLI chat → Session manager: manages sessions
- Agent loop → OpenAI client: requests response
- OpenAI client → Responses API: calls API
- Agent loop → Tool registry: dispatches tools
- Tool registry → Calculation: dispatches
- Tool registry → Weather: dispatches
- Tool registry → File reading: dispatches
- Tool registry → File writing: dispatches
- Tool registry → Web search: dispatches
- Tool registry → URL fetch: dispatches
- File reading → Path checks: validates paths
- File writing → Path checks: validates paths
- Web search → Tavily: searches
- URL fetch → Tavily: fetches pages
- Agent loop → Permission service: checks access
- Permission service → Permission rules: evaluates rules
- Agent loop → Approval handling: handles approvals
- Service container → Permission service: provides service
- Session manager → Session model: loads and saves
- Session manager → Session files: reads and writes
- HTTP API → Chat adapter: streams events