🚀 Bootstrap Agent SDK

An agent SDK for config-driven chat agents.

Describe an agent in one JSON file (model, instructions, REST APIs, MCP servers, intents) and get a production-ready chat agent built on LangChain and LangGraph, with tool use, conversation summarization, streaming events for rich UIs and token usage. No graph code to write.

Quick start · .env · API · Tools · Streaming · Configuration · Examples

_{The custom UI example: tool results render as product cards while the reply streams in.}

✨ Features

📦 Installation

Requires Python 3.10+.

pip install bootstrap-agent-sdk

Then add your API key to a .env file (see below).

git clone https://github.com/indunil-19/bootstrap_agent_sdk.git && cd bootstrap_agent_sdk
python -m venv .venv
.venv\Scripts\activate           # Windows (macOS/Linux: source .venv/bin/activate)
pip install -e .
cp .env.example .env             # then add your API key

🔐 Environment variables (.env)

API keys and other secrets live in environment variables, never in the JSON config. Put them in a .env file in your project root:

# LLM provider: the key for the provider in "llm_model"
OPENAI_API_KEY=sk-...              # openai:... (also used for OpenAI-compatible endpoints set in llm_base_url)
# ANTHROPIC_API_KEY=sk-ant-...     # anthropic:...
# GOOGLE_API_KEY=...               # google_genai:...

# LangSmith tracing (optional)
# LANGSMITH_TRACING=true
# LANGSMITH_API_KEY=lsv2_...
# LANGSMITH_PROJECT=my-agent
# LANGSMITH_ENDPOINT=https://eu.api.smith.langchain.com   # only for EU accounts

# Your own secrets, used in the config as ${NAME}
# SHOP_API_KEY=...
# JIRA_TOKEN=...

The library reads environment variables but doesn't load .env itself. Load it in your application before creating the agent:

from dotenv import load_dotenv
load_dotenv()

In production, you can set the variables in your hosting platform instead of using a .env file.

🏁 Quick start

1. Describe the agent in agent_config.json:

{
  "llm_model": "openai:gpt-4o-mini",
  "llm_temperature": 0.0,
  "agent_instructions": "You are a helpful shopping assistant. Use the tools to answer.",
  "response_instructions": "Answer in a friendly tone, in one to three sentences."
}

2. Create the agent and chat:

import asyncio
from dotenv import load_dotenv
from bootstrap_agent import ChatAgent

load_dotenv()

async def main():
    agent = await ChatAgent.create("shop", "agent_config.json")
    result = await agent.chat("Hi, what can you do?", chat_id="chat-1")
    print(result["text"])

asyncio.run(main())

📘 API

ChatAgent.create(name, config_path, tools=None, log_level=logging.INFO)

Builds the agent: loads the config and the LLM, builds the HTTP tools, connects to the MCP servers and compiles the graph.

agent.chat(message, chat_id, payload=None, chat_history=None)

Runs one turn and returns the result.

Returns:

{
    "text": "The SanDisk SSD is cheaper, but the Silicon Power one is better rated.",
    "tool_outputs": [{"call_id": "call_1", "name": "compare_products", "data": [...]}],
    "usage": {"input_tokens": 2051, "output_tokens": 746, "total_tokens": 2797, "llm_calls": 3,
              "by_step": {"agent": {...}, "response_generator": {...}}},
}

tool_outputs holds the structured data of the tools that ran (for the UI). usage is None when "token_usage": false or the provider reports no usage.

Same arguments, different output:

• agent.start_chat(...) returns only the reply text.
• agent.stream_chat(...) yields events while the turn runs (see Streaming to a UI).

💬 Chat history

The agent keeps no conversation state between calls: your application stores the messages and sends the earlier ones with every turn.

history = []

for message in ["Find a backpack under $120", "Is it waterproof?"]:
    result = await agent.chat(message, chat_id="chat-1", chat_history=history)
    history += [{"role": "user", "content": message},
                {"role": "assistant", "content": result["text"]}]

Long histories are summarized automatically, so you can always send the full list.

🔑 Payload

The payload carries per-request values that the server knows and the model must not choose or see, such as the signed-in user:

result = await agent.chat(
    "What's in my cart?",
    chat_id="chat-1",
    payload={"user_id": 42, "access_token": token},   # set from your auth, never from the browser
)

Python tools read it from their config argument, and HTTP tools insert it with {payload.key} placeholders (see below). The library also adds chat_history to the payload, and intent when intent classification is on.

🧰 Tools

🐍 Python tools

Pass any LangChain tool in tools. To give the UI structured data, use response_format="content_and_artifact" and return (text, data); the model sees only the text.

from langchain_core.runnables import RunnableConfig
from langchain_core.tools import tool

@tool(response_format="content_and_artifact")
def get_my_orders(config: RunnableConfig):
    """Get the signed-in user's orders."""
    user_id = config["configurable"]["payload"]["user_id"]   # from the payload, not the model
    orders = load_orders(user_id)
    return f"{len(orders)} orders", orders

agent = await ChatAgent.create("shop", "agent_config.json", tools=[get_my_orders])

📚 Built-in LangChain / LangGraph tools

Ready-made tools work the same way: anything that is a LangChain BaseTool, such as web search, Wikipedia or a calculator from langchain-community or a provider package.

from langchain_community.tools import DuckDuckGoSearchRun, WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

tools = [get_my_orders, DuckDuckGoSearchRun(), WikipediaQueryRun(api_wrapper=WikipediaAPIWrapper())]
agent = await ChatAgent.create("shop", "agent_config.json", tools=tools)

Install the packages these tools need (for example pip install langchain-community duckduckgo-search wikipedia).

🌐 HTTP tools

REST endpoints declared under http_tools, with no code. Each entry becomes a tool named after its key:

"http_tools": {
  "get_order": {
    "description": "Get one of the user's orders by its id.",
    "method": "GET",
    "url": "https://api.example.com/users/{payload.user_id}/orders/{order_id}",
    "params": {
      "order_id": {"type": "integer", "description": "Order id, e.g. 1042"}
    },
    "headers": {"Authorization": "Bearer {payload.access_token}", "X-Api-Key": "${SHOP_API_KEY}"},
    "response_path": "data",
    "artifact": true
  }
}

Values can use two kinds of placeholders, never visible to the model:

• ${ENV_VAR} is read from the environment once, at startup (API keys).
• {payload.key} is read from the payload on every call (per-user ids and tokens).

🔌 MCP tools

MCP servers declared under mcp_servers, using local (stdio) or remote (streamable_http) servers. tools lists which of the server's tools to load:

"mcp_servers": {
  "time": {
    "transport": "stdio",
    "command": "uvx",
    "args": ["mcp-server-time"],
    "tools": ["get_current_time", "convert_time"]
  },
  "jira": {
    "transport": "streamable_http",
    "url": "https://mcp.example.com/mcp",
    "headers": {"Authorization": "Bearer ${JIRA_TOKEN}"},
    "tools": ["search_issues"]
  }
}

MCP tools that return JSON produce UI data automatically. To see which ones do, run python -m bootstrap_agent.mcp_ui_check agent_config.json. MCP tools run out of process, so they don't receive the payload.

⚙️ How it works

Each turn runs through a LangGraph StateGraph:

Default	With intent classification

⚡ Streaming to a UI

stream_chat() takes the same arguments as chat() and yields events:

async for event in agent.stream_chat("Compare the two SSDs", chat_id="chat-1",
                                     payload={"user_id": 42}, chat_history=history):
    print(event["type"], event["data"])

Send them to the browser as Server-Sent Events, or translate them to a protocol such as AG-UI.

🔧 Configuration

"intent_classification": {
  "enabled": true,
  "intents": {
    "order_support": {"description": "Orders, delivery, refunds", "tools": ["get_order"]},
    "small_talk":    {"description": "Greetings, thanks", "route": "direct"},
    "out_of_scope":  {"description": "Unrelated requests", "route": "refuse", "message": "Sorry, I can only help with orders."}
  }
}

🧩 Examples

AG-UI: categories, product grid and details

Open WebUI: recipe and live weather cards

📄 License

Released under the Apache License 2.0.