st-agent-chat

A fully-powered agentic AI chat component for Streamlit — 12 tools, extended thinking, computer use, session persistence, subagents, and multi-provider LLM support.

Add a production-grade AI agent to any Streamlit app in one line of code. The component is completely self-contained — no sidebar, no page takeover. Drop it into any column, tab, or container. The agent can run shell commands, read/write/edit files, execute Python, search the web, grep codebases, and more.

---

Install

pip install st-agent-chat

Quick Start

import streamlit as st
from st_agent_chat import agent_chat

st.set_page_config(page_title="My AI App", layout="wide")
agent_chat(workspace=".")

That's it. You get a compact header bar, a Settings popover for provider/model selection, thinking and computer use toggles, session management, and an AI agent that can execute 12 tools on your machine.

Set Up an API Key

# Pick one (or several — the agent uses the first available)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
REPLICATE_API_TOKEN=r8_...
OPENROUTER_API_KEY=sk-or-...

Provider fallback order: Anthropic → OpenAI → Replicate → OpenRouter.

---

Tools (12 Real Executable Tools)

Tool	What it does
bash	Run any shell command (120s timeout)
file_read	Read file contents, optionally by line range (100KB max)
file_write	Create or overwrite files (auto-creates directories)
file_edit	Search-and-replace edit (exact match, must be unique)
python_exec	Execute Python code and return stdout/stderr
web_fetch	Fetch a URL; extracts readable text from HTML pages
web_search	Search the web via DuckDuckGo and return results
list_directory	List files and folders in a directory
grep_search	Search file contents with regex patterns across the workspace
glob_search	Find files by glob pattern (e.g. **/*.py)
multi_file_edit	Apply multiple file edits atomically with validation
notebook_edit	Edit Jupyter notebook cells (add, replace, delete)

All file operations are sandboxed to the workspace root. The agent chains tools automatically — ask it to "find all TODO comments and create a summary file" and it will grep, read the matches, and write the summary, all in one turn.

Key Features

Extended Thinking

Enable Claude's extended thinking for complex reasoning tasks:

agent_chat(
    workspace=".",
    extended_thinking=True,
    thinking_budget=20000,  # tokens for internal reasoning
)

Thinking content is displayed in collapsible cards in the UI. Toggle it live via Settings.

Computer Use

Enable Claude's computer use tools (screenshot, mouse, keyboard):

agent_chat(workspace=".", computer_use=True)

Session Persistence

Save and restore agent sessions to disk:

from st_agent_chat import AgentEngine, save_session, load_session, list_sessions

engine = AgentEngine(workspace=".")
engine.submit("Build a Flask app")
engine.save()  # saves to .agent_sessions/{session_id}.json

# Later...
sessions = list_sessions(".")
engine.load(sessions[0]["session_id"])

The UI has built-in Save/Load buttons in Settings.

Subagents

Spawn isolated sub-tasks with restricted tools and custom prompts:

from st_agent_chat import AgentEngine, SubagentConfig

engine = AgentEngine(workspace=".", provider="anthropic")

# Exploration subagent — read-only tools only
result = engine.run_subagent(
    "Find all database queries in this codebase",
    config=SubagentConfig(
        name="explorer",
        allowed_tools=["file_read", "grep_search", "glob_search", "list_directory"],
        max_turns=5,
    ),
)
print(result.output)

Supported LLM Providers

Provider	Models	Env Variable
Anthropic	claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5	ANTHROPIC_API_KEY
OpenAI	gpt-5.4, gpt-5.4-mini, gpt-5.4-nano	OPENAI_API_KEY
Replicate	llama-4-maverick, llama-4-scout, llama-3.3-70b	REPLICATE_API_TOKEN
OpenRouter	qwen-3.6-plus (free), nemotron-3-super (free), gemma-4-26b	OPENROUTER_API_KEY

Switch providers live from Settings — no restart needed.

---

API Reference

agent_chat()

from st_agent_chat import agent_chat

agent_chat(
    workspace="/path/to/project",   # Root for file operations (default: ".")
    provider="anthropic",           # LLM provider (default: auto-detect)
    model="claude-sonnet-4-6",      # Model ID (default: provider's default)
    api_key="",                     # API key (default: read from env)
    max_turns=25,                   # Max tool-call rounds per message
    max_tokens=8192,                # Max tokens per LLM response
    temperature=0.7,                # LLM temperature
    system_prompt="",               # Custom system prompt (default: built-in)
    extended_thinking=False,        # Enable Claude extended thinking
    thinking_budget=10000,          # Max thinking tokens
    computer_use=False,             # Enable Claude computer use tools
    show_config=True,               # Show inline Settings popover
    show_cost=True,                 # Show token usage per response
    key="my_chat",                  # Streamlit widget key
)

AgentEngine

from st_agent_chat import AgentEngine

engine = AgentEngine(
    workspace=".",
    provider="anthropic",
    extended_thinking=True,
    thinking_budget=20000,
)

result = engine.submit("List all Python files and count their lines of code")
print(result.output)
print(result.thinking)  # internal reasoning (if extended_thinking=True)
print(f"Tokens: {result.usage.input_tokens} in / {result.usage.output_tokens} out / {result.usage.thinking_tokens} thinking")
print(f"Tool calls: {len(result.tool_calls)}")

SubagentConfig

from st_agent_chat import SubagentConfig

config = SubagentConfig(
    name="reviewer",
    system_prompt="You are a code reviewer. Focus on security issues.",
    allowed_tools=["file_read", "grep_search", "glob_search"],
    max_turns=10,
)

execute_tool()

from st_agent_chat import execute_tool

result = execute_tool("bash", {"command": "git log --oneline -5"})
result = execute_tool("grep_search", {"pattern": "TODO|FIXME", "path": "src/"})
result = execute_tool("glob_search", {"pattern": "**/*.py"})
result = execute_tool("web_search", {"query": "python flask tutorial"})

---

Examples

Extended thinking + subagents

from st_agent_chat import AgentEngine, SubagentConfig

engine = AgentEngine(
    workspace=".",
    provider="anthropic",
    model="claude-sonnet-4-6",
    extended_thinking=True,
    thinking_budget=30000,
)

# Main task with deep reasoning
result = engine.submit("Analyze this codebase's architecture and suggest improvements")

# Spawn a subagent to implement one suggestion
impl_result = engine.run_subagent(
    "Refactor the database module to use connection pooling",
    config=SubagentConfig(
        name="implementer",
        max_turns=15,
    ),
)

Embed alongside other Streamlit content

import streamlit as st
from st_agent_chat import agent_chat

st.set_page_config(layout="wide")

col1, col2 = st.columns([2, 1])
with col1:
    st.metric("Users", "1,234")
    st.line_chart({"data": [1, 5, 2, 6, 3, 7]})
with col2:
    agent_chat(workspace=".", key="assistant")

---

Architecture

st_agent_chat/
├── component.py    # Streamlit UI — chat, settings, thinking display, sessions
├── engine.py       # AgentEngine — tool loop, streaming, sessions, subagents
├── llm.py          # Multi-provider LLM client (thinking, computer use)
├── tools.py        # 12 executable tools with workspace sandboxing
└── __init__.py     # Public API exports

Security

• Workspace sandboxing: All file operations confined to workspace root
• Shell timeout: bash commands have a 120-second timeout
• No credential leakage: API keys read from environment, never stored in state
• User-initiated only: Agent only acts on explicit user messages

Note: This component executes real commands on your machine. Use in trusted environments.

Development

git clone https://github.com/RhythrosaLabs/st-agent-chat.git
cd st-agent-chat
pip install -e ".[dev]"
streamlit run demo.py

License

MIT — see LICENSE.