st-agent-chat 0.1.0

Drop-in agentic AI chat component for Streamlit — your AI agent can run shell commands, read/write files, execute Python, and browse the web.

st-agent-chat

A drop-in agentic AI chat component for Streamlit.

Add a fully functional AI agent to any Streamlit app in one line of code. The agent doesn't just talk — it can run shell commands, read and write files, execute Python, and browse the web, all inside your app.

---

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 full chat interface with a sidebar for provider/model selection, a message input pinned to the bottom, and an AI agent that can actually execute tools on your machine.

Set Up an API Key

The component needs at least one LLM provider key. Set it in your environment or a .env file:

# Pick one (or several — the agent will use 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.

---

What the Agent Can Do

The agent has 7 real executable tools, not stubs:

Tool	What it does
bash	Run any shell command (120s timeout)
file_read	Read file contents, optionally by line range
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
list_directory	List files and folders in a directory

All file operations are sandboxed to the workspace root you specify. The agent cannot read or write outside that directory.

The agent chains tools automatically — ask it to "find all TODO comments and create a summary file" and it will bash grep, file_read the matches, and file_write the summary, all in one turn.

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 the sidebar — no restart needed.

---

API Reference

agent_chat()

The main component. Renders a full chat UI with tool execution.

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)
    show_sidebar=True,              # Show provider/model config in sidebar
    show_cost=True,                 # Show token usage
    key="my_chat",                  # Streamlit widget key
)

AgentEngine

The engine behind the chat UI. Use it directly for programmatic / headless agent execution:

from st_agent_chat import AgentEngine

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

# Single call — runs the full tool loop and returns the final answer
result = engine.submit("List all Python files and count their lines of code")
print(result.output)
print(f"Tokens: {result.usage.input_tokens} in / {result.usage.output_tokens} out")
print(f"Tool calls made: {len(result.tool_calls)}")

The engine maintains conversation history across calls, so follow-up messages have context.

execute_tool()

Run a single tool directly, outside the agent loop:

from st_agent_chat import execute_tool

# Shell command
result = execute_tool("bash", {"command": "git log --oneline -5"})
print(result.output)

# Read a file
result = execute_tool("file_read", {"path": "README.md"})
print(result.output)

# Run Python
result = execute_tool("python_exec", {"code": "import sys; print(sys.version)"})
print(result.output)

TOOL_SCHEMAS

The raw tool definitions (Anthropic format). Useful if you're building your own LLM integration:

from st_agent_chat import TOOL_SCHEMAS
for tool in TOOL_SCHEMAS:
    print(f"{tool['name']}: {tool['description'][:60]}...")

---

Examples

Minimal chat app

import streamlit as st
from st_agent_chat import agent_chat

st.set_page_config(layout="wide")
agent_chat()

Custom system prompt

agent_chat(
    workspace="./my_project",
    system_prompt="You are a senior Python developer. Always write tests for code you create.",
)

Headless agent in a script

from st_agent_chat import AgentEngine

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

# Multi-turn conversation
engine.submit("Create a file called hello.py with a Flask hello world app")
engine.submit("Now add a /health endpoint that returns JSON")
engine.submit("Write a test for both endpoints using pytest")

Embed alongside other Streamlit content

import streamlit as st
from st_agent_chat import agent_chat

st.set_page_config(layout="wide")

st.title("My Dashboard")
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:
    st.subheader("AI Assistant")
    agent_chat(workspace=".", show_sidebar=False, key="assistant")

---

Architecture

st_agent_chat/
├── component.py    # Streamlit UI — chat interface, CSS, sidebar
├── engine.py       # AgentEngine — agentic tool loop (submit / stream_submit)
├── llm.py          # Multi-provider LLM client with automatic fallback
├── tools.py        # 7 executable tools with workspace sandboxing
└── __init__.py     # Public API exports

The component is self-contained with no external service dependencies beyond the LLM API. All tool execution happens locally in-process.

Security

• Workspace sandboxing: All file operations are confined to the workspace root. Path traversal attempts are blocked.
• Shell timeout: bash commands have a 120-second timeout.
• No credential leakage: API keys are read from environment variables, never stored in state.
• User-initiated only: The agent only acts on explicit user messages — no background execution.

Note: This component executes real commands on your machine. Use it in trusted environments. Do not deploy with unrestricted shell access to production servers.

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.

License

MIT