AgentCore is the embeddable engine behind CLIver. Import it from cliver_core and drive it with chat(), stream(), or run_skill().

Quick Example

import asyncio

from cliver_core import AgentCore, ModelBindings, presets
from cliver_core.tools import discover_builtin_tools


async def main():
    agent = AgentCore(
        ModelBindings(llm=presets.deepseek(api_key="...")),
        builtin_tools=discover_builtin_tools(),
    )

    async for chunk in agent.stream("Analyze sales.csv"):
        if chunk.content:
            print(chunk.content, end="", flush=True)

    await agent.aclose()


asyncio.run(main())

Methods

await agent.chat(user_input, **options) → CLIverResponse

Non-streaming chat. Returns the final response with its message, usage, and any media.

response = await agent.chat(
    "What's in this directory?",
    system_prompt="You are a DevOps assistant.",
    conversation=previous_messages,
    max_iterations=30,
)
print(response.message.content)

agent.stream(user_input, **options) → AsyncIterator[CLIverMessageChunk]

Streaming chat. Yields content deltas and tool-call chunks as they arrive.

async for chunk in agent.stream("Write a README"):
    if chunk.content:
        print(chunk.content, end="", flush=True)
    if chunk.tool_call_chunks:
        print("\n[Calling tools...]")

await agent.run_skill(name, user_input, **options) → CLIverResponse

Runs the Re-Act loop with a skill pinned — see Skills.

Media Methods

image(), video(), tts(), asr(), embed(), and rerank() call the bound models directly. Their submit_* variants return a MediaJob whose result() resolves when generation finishes.

Common Parameters

Parameter	Description
system_prompt	Additional system content for this call
conversation	Previous messages for multi-turn context
media	Images/audio/video attached to the user message
extra_tools	Additional tools for this call only
mcp_servers	MCP server names to advertise for this call
tool_filter	Predicate to filter advertised tools
options	Wire request options (override binding defaults)
max_iterations	Max Re-Act iterations (default: 50)
execution_policy	Per-call execution policy
skill_dispatch	Advertise skill dispatch tools (default: on)

Event Handling

Pass on_event= to observe inference and tool lifecycle events:

from cliver_core.events import ToolEventType


async def on_event(event):
    if getattr(event, "event", None) == ToolEventType.START:
        print(f"Running: {event.tool_name}")
    elif getattr(event, "event", None) == ToolEventType.END:
        print(f"Done: {event.tool_name} ({event.duration_ms}ms)")


agent = AgentCore(bindings, on_event=on_event)

Events cover inference (inference.started, inference.first_token, inference.chunk, inference.tool_call, inference.completed, inference.error) and tool execution (tool.start, tool.end, tool.error, tool.permission_denied).