linch

Tiếng Việt · Tài liệu tiếng Việt

Linch 3.0 is a headless Python agent kernel. Applications embed its async agent loop, provide tools and permissions, and consume streamed events. The host owns the HTTP API and deployment.

Python 3.11+ is required. Linch 3.0 breaks compatibility with 2.x. See the 3.0 migration guide.

Features

Postgres is the durable backend. InMemory stores are for tests and development. Read-scoped tools can run in parallel. An input-aware parallel predicate also allows read-only subagent calls; write/exec tools with boolean flags stay serial.

Install

From a checkout:

pip install -e .

Install the extras your application uses:

pip install -e '.[postgres,worker,anthropic,gemini,mcp]'

OpenTelemetry's API is included in core. Install opentelemetry-sdk and an exporter in the host to collect telemetry.

Quickstart

This example runs without credentials or network access. ScriptedProvider is an eval extension that supplies a fixed response.

import asyncio

from linch import Agent, InMemorySessionStore
from linch.ext.evals import ScriptedProvider, TextTurn


async def main() -> None:
    """Run one offline conversation and print its result."""
    agent = Agent(
        model="demo-model",
        provider=ScriptedProvider([TextTurn(text="Hello from Linch.")]),
        session_store=InMemorySessionStore(),
    )
    try:
        session = await agent.session()
        async for event in session.run("Say hello"):
            if event.type == "result":
                print(event.final_text)
    finally:
        await agent.close()


asyncio.run(main())

Expected output: Hello from Linch. For a live provider, tools, and durable stores, follow the quickstart guide. Production hosts configure both session and run stores explicitly; the production guide covers workers, streaming, resume, and shutdown.

Documentation

• Usage index: setup and examples for each feature.
• Architecture index: module boundaries, contracts, and invariants.
• Migration from 2.x: removed APIs and replacement imports.
• Versioning: public API, prereleases, and persisted formats.
• Examples: runnable examples grouped by subsystem.
• Contributing: development and review rules.

Kernel imports come from linch.__all__. Import extensions explicitly, for example from linch.ext.workflow import run_workflow; they are absent from the kernel's top-level exports.

Build with a coding agent

Give Claude Code, Codex, or another coding agent the build-agent-with-linch skill. It tells the agent where the installed docs are and how to build and test on Linch.

npx skills add DuyTa506/linch   # from GitHub
linch skill install             # offline, matches the installed Linch version

linch new includes the skill. See the CLI guide.

Development

pip install -e '.[dev,postgres,worker,mcp,anthropic,gemini]'
python -m pytest -q
ruff check . && ruff format --check .
pyright