Metadata-Version: 2.4
Name: calfkit
Version: 0.12.2
Summary: A framework to build powerful AI agent teams.
Project-URL: Homepage, https://github.com/calf-ai/calfkit-sdk
Project-URL: Repository, https://github.com/calf-ai/calfkit-sdk
Project-URL: Issues, https://github.com/calf-ai/calfkit-sdk/issues
Author: Calf AI
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,decoupled,distributed,event-driven,kafka,llm,workflows
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.80.0
Requires-Dist: dishka>=1.9.1
Requires-Dist: exceptiongroup>=1.2.2; python_version < '3.11'
Requires-Dist: faststream[kafka]>0.7
Requires-Dist: genai-prices>=0.0.48
Requires-Dist: griffe<3,>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: ktables>=0.4.0
Requires-Dist: mcp>=1.27.2
Requires-Dist: openai>=1.0.0
Requires-Dist: opentelemetry-api>=1.28.0
Requires-Dist: pydantic-graph<2,>=1.47.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: typer>=0.12
Requires-Dist: typing-extensions>=4.15.0
Requires-Dist: typing-inspection>=0.4.0
Requires-Dist: uuid-utils>=0.14.0
Requires-Dist: watchfiles>=0.21
Provides-Extra: dev
Description-Content-Type: text/markdown

<h1 align="center">🐮 Calfkit</h1>

<h3 align="center">
  Build powerful AI agents that automatically discover each other and collaborate.
</h3>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/github/license/calf-ai/calfkit-sdk" alt="License"></a>
  <a href="https://pypi.org/project/calfkit/"><img src="https://img.shields.io/pypi/v/calfkit" alt="PyPI version"></a>
  <a href="https://pepy.tech/project/calfkit"><img src="https://static.pepy.tech/badge/calfkit/month" alt="PyPI downloads"></a>
  <a href="https://pypi.org/project/calfkit/"><img src="https://img.shields.io/pypi/pyversions/calfkit" alt="Python versions"></a>
  <a href="https://codecov.io/gh/calf-ai/calfkit-sdk"><img src="https://codecov.io/gh/calf-ai/calfkit-sdk/graph/badge.svg?token=ZUP383PSK7" alt="codecov"></a>
  <a href="https://deepwiki.com/calf-ai/calfkit-sdk"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></a>
</p>

Calfkit agents dynamically find each other at runtime and choreograph work. No hard-coded orchestrator or extra wiring. The framework for building free-flowing and powerful multi-agent teams.

<br>

## Installation

```bash
pip install calfkit
```

## Quickstart

### An agent (that can discover other agents)

```python
from calfkit import Agent, Handoff, Messaging, Tools, OpenAIResponsesModelClient

general = Agent(
    name="general",
    description="Answers simple questions and routes requests to whoever can handle it.",
    system_prompt="You are a general assistant. Defer technical questions to other agents.",
    model_client=OpenAIResponsesModelClient(model_name="gpt-5.4-mini"),
    peers=[
        Messaging(discover=True),  # discover and delegate to any agent at runtime
        Handoff(discover=True),  # discover and hand off to any agent at runtime
    ],
)
```

### Runtime discoverability allows you to add new agents and tools to the team at any time

```python
from calfkit import Agent, agent_tool, Tools, ToolContext, OpenAIResponsesModelClient

finance = Agent(
    name="finance",
    description="Answers the user's personal finance questions.",
    system_prompt="You are the personal finance specialist. Use tools to look up user data.",
    model_client=OpenAIResponsesModelClient(model_name="gpt-5.4-mini"),
    tools=[Tools(discover=True)],   # discover and use any tool at runtime
)

@agent_tool
def lookup_account_balance(ctx: ToolContext) -> str:
    """Look up the user's current account balance in USD."""
    return f"Account balance: ${ctx.deps.get('balance', '0.00')}"
```

## Running your agents

Agents sit on a mesh. Set the `CALFKIT_MESH_URL` environment variable.

Start the general assistant independently. Assuming it's saved in `general_help.py`.

```bash
# using the ck CLI
ck run general_help:general
```

Separately, start the `finance` agent and the `lookup_account_balance` tool node. Assuming it's saved in `finance_help.py`.

```bash
ck run finance_help:finance finance_help:lookup_account_balance
```

Ask the general assistant a question. Notice it's able to dynamically discover and consult the `finance` agent for help without any hard-coded configuration of `finance` agent's existence.

```python
import asyncio
from calfkit import Client

async def main():
    async with Client.connect() as client:
        result = await client.agent(name="general").execute(
            "Do I have enough money to afford a new car?"
        )
        print(result.output)
        # LOL nah twin

if __name__ == "__main__":
    asyncio.run(main())
```

```bash
python ask.py
```

Calfkit agents discover and communicate over an agent mesh, provided by either Calfkit Cloud (in alpha) or your own self-hosted version. 

Start one locally with Docker:
```bash
git clone https://github.com/calf-ai/calfkit-broker && cd calfkit-broker && make dev-up
```

Or skip the self-hosting with [Calfkit Cloud](https://forms.gle/Rk61GmHyJzequEPm8) — a fully-managed agent mesh your agents can join from anywhere.

## Why Calfkit?

- **Dynamic agent-to-agent discovery and collaboration.** Agents find each other at runtime and work together — messaging each other and handing off tasks — so you build multi-agent systems without complex wiring or orchestration, and extend team capabilities at any time.
- **No bottleneck, no single point of failure.** Every agent runs and scales as an independent microservice, so your agent teams are resilient and scalable from day one.
- **Act on live data in realtime.** Agents are event-driven so they act on realtime data streams, sending live results wherever they're needed — build agents that work like continuous workflows, not one-off requests.

## Examples

See [`examples/`](examples/) for more examples.

**Agent teams** — dynamic multi-agent choreography with `Messaging`, `Handoff`, and runtime discovery:

- **[Internal help desk](examples/help_desk/)** — a front desk that discovers expert teams at runtime (`discover=True`) and either messages them or hands off a task; deploy a new expert and it's reachable next turn, no code change.
- **[Newsroom](examples/newsroom/)** — an editor consults a researcher and a fact-checker (messaging), then hands off to a writer — both peer verbs in one run.
- **[Expense approval](examples/expense_approval/)** — a request climbs a `team_lead` → `director` → `vp` handoff chain until someone is authorized to clear it.
- **[Launch review](examples/launch_review/)** — a release manager fans out to engineering, security, and legal (messaging), then synthesizes a go/no-go itself.

**More examples:**

- **[Streaming intermediate work](examples/streaming/)** — a trip-planner agent whose preamble, tool calls, and tool results stream to the caller via `handle.stream()`, for a live view of a run's progress.
- **[Agent, tool & consumer](examples/quickstart/)** — a weather agent and its `get_weather` tool deployed as separate services and invoked over the broker, with a consumer node tapping the agent's output stream.
- **[Multi-agent panel](examples/multi_agent_panel/)** — three persona agents (`optimist`, `skeptic`, `pragmatist`) debate over one shared transcript, each automatically seeing the thread from its own point of view.
- **[MCP toolbox](examples/quickstart_mcp/)** — give an agent a live web-`fetch` tool from an MCP server, deployed as its own node and referenced by name — the agent's code never imports it.

## Documentation

In-repo documentation lives under [`docs/`](docs/).

**New to building agent teams?** Start with the tutorial **[Build a multi-agent support desk](docs/multi-agent-support-desk.md)** — build and run three agents that discover each other and collaborate by messaging and handoff.

**How-to guides** — goal-oriented walkthroughs:

- **[How to call agents from a client](docs/client-features.md)** — the `agent(name)` gateway and its `send` / `start` / `execute` triad, multi-turn conversations, runtime dependency injection (`deps`), temporary instructions, streaming a run's intermediate steps live with `handle.stream()`, the `events()` firehose, and the typed client errors.
- **[How to tap a topic with a consumer node](docs/consumer-nodes.md)** — terminal sinks that run arbitrary Python against every event on a topic; tap an agent's `publish_topic` to log, persist, or fan out.
- **[How to guard and transform node invocations](docs/policy-seams.md)** — guard an invocation with `before_node` (transform the input, short-circuit the body, or raise to block), and validate or reshape its output with `after_node`.
- **[How to handle errors and faults](docs/error-handling.md)** — recover from a failed node or callee with `on_node_error` / `on_callee_error`, mint typed faults with `NodeFaultError`, and inspect an `ErrorReport`.
- **[How to let agents discover and use tools at runtime](docs/tool-discovery.md)** — reference deployed function tool nodes by name (or every live one with `discover=True`) with `Tools`; agents discover their schemas at runtime, so an agent's deployment never imports the tool's code.
- **[How to give agents MCP tools](docs/mcp-tool-discovery.md)** — deploy an `MCPToolboxNode` fronting an MCP server and pass it to agents like a tool node; tools are discovered and kept fresh across processes automatically.
- **[How to let agents find and reach each other at runtime](docs/agent-peers.md)** — agents discover each other by name (no hardcoded addresses) and collaborate two ways: consult a peer and keep control (`Messaging`), or transfer control to a specialist (`Handoff`).
- **[Worker lifecycle & embedding](docs/worker-lifecycle.md)** — open long-lived resources at startup and close them on shutdown, publish presence events, and run with `run()`, the embeddable `start()`/`stop()`, or `async with worker:`.

**Reference:**

- **[API reference](docs/api.md)** — the public surface re-exported from the top-level `calfkit` package, with the key entry-point signatures.
- **[CLI reference](docs/cli.md)** — the `ck run` and `ck topics` commands.
- **[Topic provisioning](docs/topic-provisioning.md)** — the experimental, opt-in topic-creation helper for dev/CI.

## Contributing

Issues and pull requests are welcome. Please [open an issue](https://github.com/calf-ai/calfkit-sdk/issues) to discuss substantial changes before sending a PR.

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the quality gates (`make fix` / `make check` / `make test`), PR conventions, and how to write and run tests — including the real-broker integration tests.

## License

This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
