Nexau Evolution Guide

NexAU Evolution Guide — Simple Agent Starting Point

The code agent starts simple: a single run_shell_command tool, no middleware, no skills, no sub-agents. Evolution progressively adds components to improve performance. This guide covers what you can add and how to add it.

Current Agent Baseline

# workspace/code_agent.yaml (starting state)
type: agent
tools:
  - name: run_shell_command
    yaml_path: ./tool_descriptions/run_shell_command.tool.yaml
    binding: tools.shell_tools:run_shell_command
# No middleware, no skills, no sub_agents

Everything below is available to add during evolution.

Validation

After any change, always validate:

python evolve_agent/skills/nexau-evolution-guide/scripts/validate_agent.py workspace/code_agent.yaml

Adding Tools

The agent only starts with run_shell_command. Add tools to give the agent more capabilities.

Available Built-in Tools

These tool implementations already exist in workspace/tools/ and can be registered by adding entries to code_agent.yaml:

How to Register a Tool

Add to tools: in workspace/code_agent.yaml:

tools:
  - name: read_file
    yaml_path: ./tool_descriptions/read_file.tool.yaml
    binding: tools.file_tools:read_file

Each tool needs:

1. Tool YAML (tool_descriptions/*.tool.yaml) — schema + description for the LLM
2. Python binding (tools/*.py) — the implementation
3. Registration in code_agent.yaml under tools:

If adding complete_task, also set stop_tools: [complete_task].

Creating a New Tool

Step 1 — YAML definition (workspace/tool_descriptions/my_tool.tool.yaml):

type: tool
name: my_tool
description: >-
  What the tool does, when to use it, and any caveats.
input_schema:
  type: object
  properties:
    param_name:
      type: string
      description: Parameter description
  required:
    - param_name
  additionalProperties: false
  $schema: http://json-schema.org/draft-07/schema#

Step 2 — Python implementation (workspace/tools/my_module.py):

from typing import Any

def my_tool(*, param_name: str, agent_state=None) -> dict[str, Any]:
    # agent_state.get_sandbox() — sandbox for file/shell operations
    # agent_state.global_storage — GlobalStorage object (NOT a dict, use .get()/.set())
    # agent_state.get_global_value(key, default) / .set_global_value(key, value)
    # Omit agent_state/sandbox from signature if not needed
    result = f"Processed {param_name}"
    return {
        "content": result,           # Sent to LLM as tool result
        "returnDisplay": result,     # Shown to user
    }

Step 3 — Register in code_agent.yaml:

tools:
  - name: my_tool
    yaml_path: ./tool_descriptions/my_tool.tool.yaml
    binding: tools.my_module:my_tool

⚠️ CRITICAL: All three steps required. Missing any unavailable or agent crashes.

Tool Modification Ideas

Adding Middleware

The agent starts with no middleware. Middleware hooks into the execution pipeline to modify behavior at various points. Register middleware in code_agent.yaml under middlewares:.

Order matters: before_* hooks run top-to-bottom; after_* hooks run bottom-to-top.

AgentState & GlobalStorage API

Middleware and tools access runtime state via agent_state. global_storage is NOT a dict — it is a thread-safe GlobalStorage object. Do NOT use dict methods like [], setdefault(), in, or pop().

AgentState API:

GlobalStorage API (agent_state.global_storage):

Common mistakes:

# ❌ WRONG — GlobalStorage is not a dict
storage = agent_state.global_storage
storage.setdefault("key", [])     # AttributeError
storage["key"] = value            # TypeError
if "key" in storage:              # TypeError

# ✅ CORRECT
storage = agent_state.global_storage
val = storage.get("key", [])      # Read with default
storage.set("key", val)           # Write

Creating Custom Middleware

Step 1 — Create workspace/middleware/my_middleware.py:

from nexau.archs.main_sub.execution.hooks import (
    Middleware, HookResult,
    BeforeModelHookInput, AfterModelHookInput,
    AfterToolHookInput, ModelCallParams, ModelCallFn,
)
from nexau.core.messages import Message, Role, TextBlock

class MyMiddleware(Middleware):
    def __init__(self, *, param_a: str = "default"):
        self.param_a = param_a

    def before_model(self, hook_input: BeforeModelHookInput) -> HookResult:
        # hook_input.messages, hook_input.current_iteration, hook_input.max_iterations
        return HookResult.no_changes()

    def after_model(self, hook_input: AfterModelHookInput) -> HookResult:
        # hook_input.parsed_response, hook_input.messages
        # Can modify: messages, parsed_response, force_continue
        return HookResult.no_changes()

    def after_tool(self, hook_input: AfterToolHookInput) -> HookResult:
        # hook_input.tool_name, hook_input.tool_output, hook_input.sandbox
        return HookResult.no_changes()

    def wrap_model_call(self, params: ModelCallParams, call_next: ModelCallFn):
        # MUST call call_next(params) to proceed
        return call_next(params)

Step 2 — Register in code_agent.yaml:

middlewares:
  - import: middleware.my_middleware:MyMiddleware
    params:
      param_a: "value"

Hook Points Reference

Middleware LLM Access

Middleware can make its own LLM calls. At runtime, these env vars are always available:

In wrap_model_call (preferred — reuse existing client):

from nexau.archs.main_sub.execution.llm_caller import LLMCaller

class MyLLMMiddleware(Middleware):
    def wrap_model_call(self, params: ModelCallParams, call_next: ModelCallFn):
        llm_caller = LLMCaller(
            params.openai_client, params.llm_config,
            retry_attempts=1, middleware_manager=None,  # None to avoid recursion
        )
        # Make side call, then: return call_next(params)

In other hooks (create standalone client):

import os, openai
from nexau.archs.llm.llm_config import LLMConfig

client = openai.OpenAI(api_key=os.environ["LLM_API_KEY"], base_url=os.environ["LLM_BASE_URL"])
llm_config = LLMConfig(model=os.environ["LLM_MODEL"], ...)
caller = LLMCaller(client, llm_config, retry_attempts=2, middleware_manager=None)

Always set middleware_manager=None to avoid infinite recursion.

Adding Sub-Agents

Sub-agents are child agents with their own prompt, tools, middleware, and isolated context window.

When to Use

Creating a Sub-Agent

Step 1 — Create config (workspace/sub_agents/verifier/agent.yaml):

type: agent
name: verifier
max_iterations: 50
max_context_tokens: 128000
system_prompt: ./prompt.md
system_prompt_type: jinja
tool_call_mode: openai

llm_config:
  model: ${env.LLM_MODEL}
  base_url: ${env.LLM_BASE_URL}
  api_key: ${env.LLM_API_KEY}
  max_tokens: 16000
  temperature: 0.3
  stream: false
  api_type: openai_chat_completion

tools:
  - name: run_shell_command
    yaml_path: ../tool_descriptions/run_shell_command.tool.yaml
    binding: tools.shell_tools:run_shell_command
  - name: complete_task
    yaml_path: ../tool_descriptions/complete_task.tool.yaml
    binding: tools.session_tools:complete_task

stop_tools: [complete_task]

Step 2 — Create prompt (workspace/sub_agents/verifier/prompt.md)

Step 3 — Register in code_agent.yaml:

sub_agents:
  - name: verifier
    config_path: ./sub_agents/verifier/agent.yaml

⚠️ CRITICAL: Framework auto-injects RecallSubAgent tool when sub_agents is non-empty. Do NOT add it manually — causes duplicate tool error.

Adding Skills

Skills are modular knowledge packages loaded at runtime via LoadSkill.

Structure

workspace/skills/my-skill/
├── SKILL.md              ← Required: YAML frontmatter + content
├── scripts/              ← Optional
└── references/           ← Optional

SKILL.md Format

---
name: my-skill-name
description: When to use this skill and what it provides.
---

# Skill content loaded when agent calls LoadSkill...

Registration

skills:
  - ./skills/my-skill      # Each folder listed individually
  - ./skills/another-skill  # Does NOT recursively scan!

⚠️ CRITICAL: Without registration in skills:, the agent cannot discover or load the skill.

YAML Config Reference (code_agent.yaml)

type: agent
name: string
max_iterations: 300
max_context_tokens: 200000
tool_call_mode: "openai"             # "openai" | "xml" | "anthropic"
system_prompt: ./systemprompt.md
system_prompt_type: jinja            # "string" | "file" | "jinja"

llm_config:                          # 🚫 DO NOT MODIFY
  model: ${env.LLM_MODEL}
  # ... (hands-off)

tools: [...]
stop_tools: [complete_task]
middlewares: [...]
sub_agents: [...]
skills: [...]

tracers:
  - import: nexau.archs.tracer.adapters.in_memory:InMemoryTracer

Reference Docs

Detailed NexAU v0.3.9 documentation is available in reference/: