agent() Agents

Use agent() to build either a short tool-using agent or a long-horizon RLM agent with a typed final response.

var helper = Ax.agent("question:string -> answer:string");

Agents coordinate tools, child agents, runtime sessions, memories, skills, context policies, discovery, recall, shared fields, traces, usage, and final typed responses.

Pick the path by task shape:

• Short agents: quick tool calls, small child-agent composition, and compact final responses.
• Long-horizon agents: RLM runtime execution, context policy, context maps, memory, skills, and optimizer artifacts.

See short agent examples and Advanced Start for the broader Ax path.

What It Does

agent() creates a structured agent program. The agent planner/executor/responder loop can call tools, delegate to child agents, inspect runtime state, ask for clarification, discover tools or skills, recall memory, and finish with a typed output object.

Core Call Shape

helper = agent(signature, options)
result = helper.forward(aiClient, inputs)

Common Patterns

• Start with a signature that names the final answer fields.
• Add fn() tools for host data and side effects.
• Add child agents to the same callable list as tools.
• Use namespaces to keep tool calls readable.
• Enable discovery when available tools are too numerous to include in full.
• Save and restore state around clarification.
• Use context policies for long-running sessions.

Short agent

AxAgent assistant = Ax.agent(
  "question:string -> answer:string",
  Map.of("contextFields", List.of())
);

Namespaced tools and discovery

Use a flat functions list for small stable sets: local fn() tools, child agents, MCP clients, and runtime providers can all live beside each other. The actor sees those callables directly.

AxAgent assistant = Ax.agent(
  "question:string -> answer:string",
  Map.of("contextFields", List.of())
);

Use grouped functions when the catalog is large or easier to reason about by domain. Each group gives the actor a namespace plus module-level selection criteria; with functionDiscovery: true, concrete schemas are loaded only after the actor calls discover(...).

AxAgent assistant = Ax.agent(
  "question:string -> answer:string",
  Map.of("contextFields", List.of())
);

Grouped mode keeps big catalogs out of the prompt until needed. Keep the top-level list either flat or grouped. If a child agent belongs inside a group, pass childAgent.getFunction() inside the group’s functions list.

Memory, skills, and context policy

AxAgent assistant = Ax.agent(
  "question:string -> answer:string",
  Map.of("contextFields", List.of())
);

AxAgent assistant = Ax.agent(
  "question:string -> answer:string",
  Map.of("contextFields", List.of())
);

Connect MCP servers

MCP clients can be passed as tool providers after initialization. Use the flat form when the server exposes a small, obvious tool set.

AxMCPClient client = new AxMCPClient(transport);
client.init();
AxAgent assistant = Ax.agent("request:string -> response:string", Map.of(
  "functions", client.toFunction(),
  "functionDiscovery", true,
  "contextFields", List.of()
));

Use grouped discovery when an MCP server has many tools, prompts, or resources. The group gives the actor a namespace and selection criteria before it asks to see detailed schemas.

AxAgent assistant = Ax.agent("request:string -> response:string", Map.of(
  "functions", List.of(Map.of(
    "namespace", "memory",
    "title", "Memory MCP",
    "selectionCriteria", "Use for persistent memory lookup.",
    "functions", client.toFunction()
  )),
  "functionDiscovery", true,
  "contextFields", List.of()
));

Production Notes

Trace actor turns, tool calls, child-agent calls, clarification, discovery, recall, context growth, token usage, and final typed outputs. Keep host functions narrow and typed. Let fatal infrastructure errors bubble; let task uncertainty become clarification or a typed final answer.

See Tools, agent() API, and MCP.