Fathym
Menu

Agent Patterns

An Agent is a behavioral holon that wraps an AI interaction behind a typed input/output contract. Instead of a raw LLM call, you get a declared entity: validated input, a message-based handle, an intent, and governance hooks. Agents compose into operations, workflows, capabilities, and other agents.

The AgentHandle

.Setup() (via AgentRunner) returns a handle - the contract is SendMessage and Close. Always close it.

const Summarizer = Agent('Summarizer', 'Summarizes text using an LLM')
  .Input(z.object({
    text: z.string().describe('Text to summarize'),
    maxWords: z.number().default(100),
  }))
  .Execute(async (ctx) => ({
    SendMessage: (prompt: string) => callLLM({ ...ctx.Input, prompt }),
    Close: async () => {},
  }));

const handle = await AgentRunner(Summarizer).Setup({ text: article, maxWords: 50 });
const summary = await handle.SendMessage('Focus on the key findings');
await handle.Close();

With services

Declare .Services() to pull context from web/db/docstore via IoC, then use it inside SendMessage.

Spawn - external processes

.Spawn() lets an Agent manage an external tool or process (a CLI, a coding agent), interacting over stdin/stdout. This is how fAI wraps coding agents like Claude Code and Cursor as holons.

Self-governance

.Governance() attaches guardrails the Agent carries everywhere - e.g. block destructive actions outside production, protect system resources.

Composition - agents using agents

An orchestrator Agent can compose Planner + Executor + Validator sub-agents: the planner produces a plan, the executor runs the steps, the validator checks the result. Each sub-agent stays a distinct holon.

Install and metadata

.Install() with .AutoInstall(true) lets an Agent self-provision a dependency (check if a tool exists, install it if not). .Metadata() supplies discovery info - domain, capabilities, version, provider - so agents can be selected dynamically.

Running agents

  • Directly: AgentRunner(agent).Setup(input) → handle.
  • In an Operation: ctx.Agents.AgentName(input) (registered via .Agents({})).
  • In a Workflow flow function: await ctx.Agents.AgentName(input).
On this page