API Guide Overview

This chapter walks through the API exposed by the xun package, feature by feature. Import names and signatures in the examples match the source; snippets labelled as pseudo-code only illustrate behaviour. Set XUN_OPENAI_BASE_URL and XUN_OPENAI_API_KEY before running them (see Configuration); more executable examples live in demo.ipynb at the repository root.

Module map

flowchart LR
  ENTRY["Entry<br/>entrypoint.py"] --> AGENT["Agent<br/>agent.py"]
  CONFIG["Config<br/>config.py"] --> AGENT
  AGENT --> LOOP["Execution loop<br/>loop.py"]
  HOOKS["Hooks and commands<br/>hooks.py · command.py"] --> LOOP
  LOOP --> CONV["Conversation and compaction<br/>conversation.py · compact.py"]
  LOOP --> TOOLBOX["Tools<br/>toolbox.py · tools"]
  LOOP --> DISPLAY["Display<br/>display_abstract.py · displays"]
  EXT["Extensions<br/>extension.py"] --> AGENT

Public exports

Names available through from xun import ... (see src/xun/__init__.py):

Group	Names
Agent	Agent, AgentConfig, Workspace
Tools	ToolBox, ToolCallContext, tool_attr
Sub-agents	AgentGetterProtocol, AgentGetterParam
Display	DisplayAbstract, Display, NullDisplay, WebDisplay, WebDisplayService
Commands & hooks	Command, CommandRegistry, HookArgs, Hooks
Compaction	CompactorAbstract, AutoCompactor
Session entry points	setup_agent, interactive_session, web_session, main, main_serve, main_container
Result types	Result, ToolResultType, ErrorInfo, CancelledError
Extensions	ExtensionContext, extension_attr, xun_version

The lifecycle state namespace T (T.Uninit / T.Init / T.Final) is not in __all__; access it through Agent.T.

Minimal skeleton

from xun import Agent, AgentConfig, ToolBox, NullDisplay

def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

agent = Agent(
    toolbox=ToolBox().register(add),
    display=NullDisplay(),
    config=AgentConfig.default(),      # skips config.json, but still reads ${XUN_*} from os.environ
).initialize()

answer = agent.instruct("What is 2 + 3?").execute()
if answer.is_ok():
    print(answer.unwrap())
else:
    print(answer.unwrap_err().error)

When you need the full set of built-in tools, the default system prompt and the session commands, use setup_agent(default_tools=True) instead; it already returns an initialised agent.

Glossary

Term	Meaning
Tool	An ordinary callable registered in a ToolBox, exposed to the model as a JSON Schema
Turn / step	A single model call together with the set of tool calls it triggers
Event	A payload the agent broadcasts to the display layer (ToolCallEvent, InfoEvent …)
Hook	A registrable callback on the execution path; its argument object can be modified in place
Extension	A source file placed under $XUN_HOME/extensions/ and replayed whenever an agent is initialised
Workspace	The set of directories an agent may read and write: workdir + a lazily created temporary directory