Agents

An agent combines an LLM, a system prompt, and a set of tools to accomplish tasks autonomously.

An agent is the central building block in NexAU. It wraps an LLM with a system prompt and a collection of tools, then runs an iterative loop — calling the LLM, executing tools, and updating context — until it produces a final answer.

Creating an agent

You can define an agent entirely in Python, or load its configuration from a YAML file.

Python

Import Agent, AgentConfig, LLMConfig, and Tool from nexau, then build a config and instantiate the agent.

import os
from nexau import Agent, AgentConfig, LLMConfig, Tool
from nexau.archs.tool.builtin.web_tools import google_web_search, web_fetch

# Load tool schemas and bind them to Python functions
web_search_tool = Tool.from_yaml("tools/WebSearch.yaml", binding=google_web_search)
web_read_tool = Tool.from_yaml("tools/WebRead.yaml", binding=web_fetch)

# Configure the LLM
llm_config = LLMConfig(
    model=os.getenv("LLM_MODEL"),
    base_url=os.getenv("LLM_BASE_URL"),
    api_key=os.getenv("LLM_API_KEY"),
)

# Build the agent
agent_config = AgentConfig(
    name="research_agent",
    system_prompt="You are a research agent. Use web_search and web_read to find information.",
    tools=[web_search_tool, web_read_tool],
    llm_config=llm_config,
)
agent = Agent(config=agent_config)

YAML

Define the agent in a YAML file, then load it with AgentConfig.from_yaml. You still set llm_config in Python so credentials stay out of version control.

agents/my_agent.yaml

type: agent
name: my_research_agent
max_context_tokens: 100000
system_prompt: |
  Date: {{date}}. You are a research agent specialized in finding and analyzing information.
  Use web_search to find relevant information, then web_read to get detailed content.
system_prompt_type: string
llm_config:
  temperature: 0.7
  max_tokens: 4096
tools:
  - name: web_search
    yaml_path: ./tools/WebSearch.yaml
    binding: nexau.archs.tool.builtin.web_tools:google_web_search
  - name: web_read
    yaml_path: ./tools/WebRead.yaml
    binding: nexau.archs.tool.builtin.web_tools:web_fetch

main.py

import os
from datetime import datetime
from pathlib import Path
from nexau import Agent, AgentConfig, LLMConfig

agent_config = AgentConfig.from_yaml(Path("agents/my_agent.yaml"))
agent_config.llm_config = LLMConfig(
    model=os.getenv("LLM_MODEL"),
    base_url=os.getenv("LLM_BASE_URL"),
    api_key=os.getenv("LLM_API_KEY"),
)

agent = Agent(config=agent_config)

response = agent.run(
    "Research the latest developments in quantum computing",
    context={"date": datetime.now().strftime("%Y-%m-%d %H:%M:%S")},
)
print(response)

The context dict is used to fill template variables (like {{date}}) in your system prompt. Pass it to agent.run() at call time.

Running an agent

Once you have an Agent instance, call .run() to execute it synchronously or .run_async() for async contexts.

Synchronous

response = agent.run("What's the latest news about AI developments?")
print(response)

Asynchronous

import asyncio

async def main():
    response = await agent.run_async("What's the latest news about AI developments?")
    print(response)

asyncio.run(main())

Both methods accept an optional context dict (for system prompt templating) and an event_handlers list for streaming callbacks.

AgentConfig reference

name · str · required

A unique identifier for this agent. Used in logs, traces, and multi-agent routing.

system_prompt · str | list

The instructions given to the LLM at the start of every run. Can be a plain string, a path to a file (system_prompt_type: "file"), or a Jinja2 template (system_prompt_type: "jinja").

system_prompt_type · str · default: "string"

Controls how system_prompt is interpreted. One of "string", "file", or "jinja".

llm_config · LLMConfig

The LLM provider and model settings. See LLM Config for all options. If omitted, NexAU reads LLM_MODEL, LLM_BASE_URL, and LLM_API_KEY from the environment.

tools · list[Tool] · default: "[]"

The tools this agent can call. Each Tool combines a YAML schema with a Python function via Tool.from_yaml(...). See Tools.

tool_call_mode · str · default: "structured"

How the agent invokes tools. "structured" uses native function-calling APIs. "xml" uses XML-in-text for models that don’t support native tool use.

max_context_tokens · int · default: "128000"

The token budget for the agent’s conversation context. When the context approaches this limit, context compaction middleware (if configured) trims history.

max_iterations · int · default: "100"

The maximum number of LLM + tool-call cycles per run. The agent stops and returns its current answer when this limit is reached.

skills · list[Skill] · default: "[]"

Skills extend the agent’s capabilities by providing lazily-loaded tool descriptions. See the Skills guide.

middlewares · list · default: "[]"

Middleware instances that intercept model calls and tool executions. See the Middleware guide.

tracers · list[BaseTracer] · default: "[]"

Tracer instances for observability. See the Observability guide.

mcp_servers · list[dict] · default: "[]"

MCP (Model Context Protocol) server configurations. Each entry requires name and type ("stdio", "http", or "sse"). See the MCP guide.