bos-ai 2.3.0

 ███████████     ███████     █████████
░░███░░░░░███  ███░░░░░███  ███░░░░░███
 ░███    ░███ ███     ░░███░███    ░░░
 ░██████████ ░███      ░███░░█████████
 ░███░░░░░███░███      ░███ ░░░░░░░░███
 ░███    ░███░░███     ███  ███    ░███
 ███████████  ░░░███████░  ░░█████████
░░░░░░░░░░░     ░░░░░░░     ░░░░░░░░░

An agent out of the box. A framework for your own agent-native applications.

Quick Start

OPENAI_API_KEY=<api-key> uvx boscli ask "how are you" --model openai/gpt-4o

Install uv to get uvx, or install the CLI permanently with uv tool install boscli / pipx install boscli.

Using a different provider? See LiteLLM's provider docs for the right BOS_MODEL prefix and required environment variables. For example, using a deepseek model

DEEPSEEK_API_KEY=<api-key> uvx boscli ask "how are you" --model deepseek/deepseek-v4-pro

pip install bos-ai installs the library — it does not provide the boscli command. The CLI ships as the boscli distribution. See Embedding to drive BOS from your own application.

Project Setup

mkdir my-agent && cd my-agent
boscli init          # guided setup: purpose, topology, model — writes a runnable baseline
boscli gateway start # start the agent runtime
boscli tui           # connect the terminal UI

Embedding

pip install bos-ai is a library install: about 14 MB, no console script, no terminal UI, no gateway. There are two ways to embed, and which one you want is a decision to make before you write code.

Call the agent from your own process — bos.sdk is the contract:

from bos.sdk import BosApp

async with BosApp(my_config_dict, bos_dir="/var/lib/myapp/.bos") as app:
    agent = app.agent()
    result = await agent.run(chat_id, "hello")

Or mount the whole gateway runtime — actors, channels, chat coordination, the WebSocket protocol — inside your own web application with GatewayMount (needs bos-ai[gateway]).

Configuration is a plain dict in both — load it from a database, environment, or a control plane; nothing requires a TOML file on disk. Embedding BOS covers the choice, both modes, and the supported API surface; examples/embed_sdk.py and examples/embed_gateway_fastapi.py are the runnable versions.

Install extras

The codex and claude-code extras let a BOS agent run on Codex or Claude Code — see External agents for declaring, configuring and logging in.

The supported surface

• bos.core — AgentHarness, Agent, AgentResult, the ep_* extension points, and the port protocols (LLM, ChatStore, Consolidator, ToolSet, TurnInterceptor, PromptProvider, TurnEventSink)
• bos.config — Workspace, RootConfig, validate_config

Names prefixed with _ are re-exported for extensions and are not stable; they are not part of the embedding contract.

Docs

See the documentation site for tutorials, architecture, extension points, and the configuration reference.

Building on BOS with an AI agent? llm-full.md is a single dense, code-grounded reference covering every mechanism — configuration, extension points, plugins, channels, skills, the CLI, and the runtime — in one file. boscli init drops a copy into every scaffolded project.

License

See LICENSE.