Skip to main content
 ███████████     ███████     █████████
░░███░░░░░███  ███░░░░░███  ███░░░░░███
 ░███    ░███ ███     ░░███░███    ░░░
 ░██████████ ░███      ░███░░█████████
 ░███░░░░░███░███      ░███ ░░░░░░░░███
 ░███    ░███░░███     ███  ███    ░███
 ███████████  ░░░███████░  ░░█████████
░░░░░░░░░░░     ░░░░░░░     ░░░░░░░░░

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

PyPI Downloads Python License GitHub Stars

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

Install Adds
bos-ai The library: bos.core, bos.config, plugins
bos-ai[litellm] The built-in LLM provider. Without it, register your own with @ep_provider
bos-ai[gateway] The gateway process and the Telegram/Lark channels
bos-ai[search] The built-in web-search and page-fetch tools
bos-ai[lark] The Lark/Feishu SDK
bos-ai[cli] The CLI's dependencies — run it with python -m bos.cli
bos-ai[codex] The Codex external agent runtime (BEP 19), with the vendor's codex CLI binary
bos-ai[claude-code] The Claude Code external agent runtime (BEP 19), with the claude CLI bundled in the claude-agent-sdk wheel (~230 MB)
bos-ai[all] Every extra above except codex and claude-code, which each bundle a vendor CLI binary

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.

Metadata

Release files for bos-ai 2.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bos-ai 2.3.1
File Size Uploaded Provenance Actions
bos_ai-2.3.1.tar.gz 1.3 MB With provenance Details for bos_ai-2.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bos-ai 2.3.1
File Interpreter ABI Platform Actions
bos_ai-2.3.1-py3-none-any.whl Python 3 none any Details for bos_ai-2.3.1-py3-none-any.whl

Total release size: 1.7 MB

Release files / bos_ai-2.3.1.tar.gz

Download URL bos_ai-2.3.1.tar.gz
Size 1.3 MB
Tags Source
SHA-256 checksum
How to use checksums
27677a74ad2920b00aedf9a9f4ee73f373cd5405db4afa7f754a7e0aed501eda
BLAKE2b-256 checksum
How to use checksums
9ada85fd510df4403ef7b4844d177dd935a779c6c57ef6d217f308a23fcf52b6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

Release files / bos_ai-2.3.1-py3-none-any.whl

Download URL bos_ai-2.3.1-py3-none-any.whl
Size 440.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4c414968a8c6b16ce3adc9dc651eca3f43f5d78ef3fcbfc23538527a68cd2c00
BLAKE2b-256 checksum
How to use checksums
6b8aaf8847bd2292b2805ca33b981b8e9fa2d3266850866588486e5410a75502
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

Security for bos-ai 2.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for bos_ai-2.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page