honcho Agent工作流

Quick start (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 self-host and run against http://localhost:8000.

Example

If you have this in config.toml:

[db]
CONNECTION_URI = "postgresql+psycopg://localhost/honcho_dev"
POOL_SIZE = 10

You can override just the connection URI in production:

export DB_CONNECTION_URI="postgresql+psycopg://prod-server/honcho_prod"

The application will use the production connection URI while keeping the pool size from config.toml.

</details>

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.

<details> <summary>Full configuration reference</summary>

Using config.toml

Copy the example configuration file to get started:

cp config.toml.example config.toml

Then modify the values as needed. The TOML file is organized into sections:

• [app] - Application-level settings (log level, session limits, embedding settings, namespace)
• [db] - Database connection and pool settings
• [auth] - Authentication configuration
• [cache] - Redis cache configuration
• [llm] - LLM provider API keys and general settings
• [deriver] - Background worker settings and representation configuration
• [peer_card] - Peer card generation settings
• [dialectic] - Chat Endpoint configuration with per-level reasoning settings
• [summary] - Session summarization settings
• [dream] - Dream processing configuration (including specialist models and surprisal settings)
• [webhook] - Webhook configuration
• [metrics] - Prometheus pull-based metrics
• [telemetry] - CloudEvents telemetry for analytics
• [vector_store] - Vector store configuration (pgvector, turbopuffer, or lancedb)
• [sentry] - Error tracking and monitoring settings

Using Environment Variables

All configuration values can be overridden using environment variables. The environment variable names follow this pattern:

• {SECTION}_{KEY} for top-level section settings
• Use __ inside {KEY} for nested settings
• Just {KEY} for app-level settings

Examples:

• DB_CONNECTION_URI - Database connection string
• AUTH_JWT_SECRET - JWT secret key
• DERIVER_MODEL_CONFIG__TRANSPORT - Transport for the background deriver
• SUMMARY_MODEL_CONFIG__MODEL - Summary model override
• DIALECTIC_LEVELS__low__MODEL_CONFIG__MODEL - Model for low reasoning level
• LOG_LEVEL - Application log level
• METRICS_ENABLED - Enable Prometheus metrics
• TELEMETRY_ENABLED - Enable CloudEvents telemetry

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/

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