honcho Agent工作流

Quick start (from source, Docker)

git clone https://github.com/plastic-labs/honcho.git
cd honcho
cp docker-compose.yml.example docker-compose.yml
cp .env.template .env       # fill in LLM_GEMINI_API_KEY / LLM_ANTHROPIC_API_KEY / LLM_OPENAI_API_KEY
docker compose up

Then point the SDKs at it:

```python honcho = Honcho(workspace_id="my-app-testing", base_url="http://localhost:8000")

Quickstart

Get an API key at app.honcho.dev — when you sign up you'll be prompted to join an organization, which gets its own dedicated Honcho instance and $100 free credits. Or install the CLI and run honcho start --setup, then point the SDK at http://localhost:8000.

Configuration

Honcho uses a flexible configuration system that supports both TOML files and environment variables. Configuration values are loaded in priority order: environment variables > .env file > config.toml > defaults.

Copy the example file to get started:

cp config.toml.example config.toml

The file is organized by subsystem — [app], [db], [auth], [cache], [llm], [deriver], [dialectic], [summary], [dream], [peer_card], [webhook], [metrics], [telemetry], [vector_store], and [sentry]. Any value can be overridden by an environment variable named {SECTION}_{KEY}, using __ for nesting (DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL), or just {KEY} for app-level settings.

See the configuration reference for every available option, and .env.template for an annotated list of environment variables.

Managed service uses api.honcho.dev by default. For self-hosted, pass

or: bun add @honcho-ai/sdk

const honcho = new Honcho({ workspaceId: "my-app-testing", apiKey: process.env.HONCHO_API_KEY, });

const alice = await honcho.peer("alice"); const tutor = await honcho.peer("tutor"); const session = await honcho.session("session-1"); await session.addMessages([ alice.message("Hey there — can you help me with my math homework?"), tutor.message("Absolutely. Send me your first problem!"), ]);

const answer = await alice.chat( "What learning styles does the user respond to best?", ); const context = await session.context({ summary: true, tokens: 10_000 });

const openai = new OpenAI(); const completion = await openai.chat.completions.create({ model: process.env.OPENAI_MODEL ?? "gpt-4o-mini", messages: context.toOpenAI({ assistant: tutor }), }); ```

Note: background reasoning is asynchronous. Newly-added messages may take a moment to be reflected in chat/representation responses; for low-latency reads, use the representation endpoint.

LLM Provider API Keys

LLM_GEMINI_API_KEY= # API Key for Google Gemini (used for deriver, summary, and dialectic minimal/low by default) LLM_ANTHROPIC_API_KEY= # API Key for Anthropic (used for dialectic medium/high/max and dream by default) LLM_OPENAI_API_KEY= # API Key for OpenAI (used for embeddings when EMBED_MESSAGES=true)

> Note that the `DB_CONNECTION_URI` must have the prefix `postgresql+psycopg` to
> function properly. This is a requirement brought by `sqlalchemy`

The template has the additional functionality disabled by default. To ensure
that they are disabled you can verify the following environment variables are
set to false:

If you set `AUTH_USE_AUTH` to true you will need to generate a JWT secret. You can
do this with the following command:

This will generate a JWT secret and print it to the console. You can then set
the `AUTH_JWT_SECRET` environment variable. This is required for `AUTH_USE_AUTH`:

Once auth is enabled, use `scripts/generate_jwt.py` to mint tokens for local
development and scripting:

SDKs

• Python — honcho-ai on PyPI · source in sdks/python/
• TypeScript — @honcho-ai/sdk on npm · source in sdks/typescript/
• CLI — honcho-cli on PyPI · source in honcho-cli/ · CLI reference

SDKs are versioned independently of the server. Current SDK versions track each other; the server badge above reflects the deployed server version.

See the SDK Reference for full API surface, the API Reference for the raw HTTP API, and per-SDK example folders for runnable demos.

Integrations

Honcho ships a first-party memory plugin for every major coding agent. They all read the same ~/.honcho/config.json, so one key configures all of them — and pointing two at the same workspace gives them one shared memory.

Get a key at app.honcho.dev, then honcho init (or uv tool install honcho-cli && honcho init) writes it to ~/.honcho/config.json once for every integration.