xdog / Packages / agent / Reference

Public Python imports use xdog.agent, not agent. Requires Linux/Python 3.12+. Hosts retain permissions, resources and storage ownership.

Core API

A basic SDK call (login/network needed for generation):

import asyncio
import xdog.ai as ai
from xdog.agent import Agent, AgentConfig, stream_fn_from_provider

async def main():
    async with Agent(
        stream_fn_from_provider(ai.provider("copilot")),
        config=AgentConfig(model="claude-sonnet-4.5"),
    ) as agent:
        stream = await agent.prompt("Explain host-owned tools")
        async for event in stream:
            print(event.type)
        await stream.result()  # Completion only, not the retained history.
        print(len(agent.messages))

asyncio.run(main())

Consume events while the producer runs: the default 256-event buffer applies backpressure. Awaiting only result() can stall. Bare Agent creates no default shell/filesystem tools or capabilities.

Built-in tools and registry

A repo example inside an async host with an existing idle agent:

from pathlib import Path
from xdog.agent import ToolRepo
from xdog.agent.tools import create_submit_result_tool

repo = ToolRepo(cwd=Path.cwd())
selected = repo.select(("current_time",))
assert selected.get("current_time") is repo.get("current_time")
receipt = selected.register(create_submit_result_tool())
selected.publish(agent)
receipt.close()  # Only this registration; never a later replacement.
selected.publish(agent)

ToolRepo(builtin=False) starts empty; register(*tools) is atomic and never silently replaces a different same-name tool. Replacement explicitly calls unregister(name) then register(replacement). names() returns a frozenset; get(name) raises ValueError when missing; tools is a tuple. Removal does not close resources or undo effects. agent.local_tools is ordinary inventory, state.tools is combined inventory and active_tools is effective selection. MCP connects separately and closes after Agent cleanup; extensions do not register model tools.

SkillRepo(builtin=True, packaged=None) discovers installed packaged skills. SkillRepo(builtin=False) disables default discovery. Add sources with chainable .register(directory=path, name="host"). Directory-name and different same-slug conflicts fail, never shadow. from_packaged / select / merge are SDK methods. The read-only skill entry exposes list/load; bodies are not injected by default. Native Agent retains its tools and skills parameters.

For submit_result, inject a new shared sink per collection through tool_ctx={"result_schema": schema, "result_sink": sink}. The outer context is shallow-copied by ToolDef dispatch; the nested sink carries the accepted value. JSON Schema objects with type/properties and legacy flat field/type mappings are supported; no schema accepts any JSON value. Validation errors return Error: ... for correction. Old flow_output_schema/flow_result_sink keys are rejected. Acceptance neither stops the Agent nor proves durable task completion; the caller must check the sink and overall outcome.

Lifecycle and composition

Configure Set repositories before selection/open. Select provider names before startup; application scope may omit host, session/group need real owner ports. Assembly takes additive tool_repo / skill_repo, not native tools / skills or separate enable lists. An empty supplemental subset cannot remove capability contributions. compose_tools(existing) / publish_tools(agent) have no extra filter parameter. Flow/Eyes/Goal bodies are not default-active; skill text never grants tools or approval. Closing Eyes detaches from its daemon, not daemon stop. Flow CLI does not inherit host sandbox, approval hooks or tool allowlists. Close Agents before shared Sets; children receive actual grants, not the whole application Set. Coding/Claw own child runtimes and persistence.

CLI — xdog-agent

Without --no-tools, the CLI constructs default ToolRepo tools, injects search and opens application capabilities. It is not a host approval sandbox.

Chat slash commands

Full SDK reference, registry API and capability assembly example.