Agent API

Purpose and Scope

The Agent API is the public runtime surface for defining Flue agents and running agent operations from application code. The documentation page identifies the package boundary explicitly: these symbols are exported from @flue/runtime, which means application authors should treat this API as the stable entrypoint rather than importing from internal runtime modules. In Flue terminology, an agent is not only a model call. It is a programmable harness: instructions, tools, skills, stateful sessions, sandbox execution, and optional delegated subagents assembled into a durable resource that can be invoked by routes, channels, workflows, or local development tools.

Sources: apps/docs/src/content/docs/api/agent-api.md

This reference is useful when you need to choose the right primitive for an agent-facing task. Use definition helpers when declaring reusable capabilities, dispatch types when starting work, session types when interacting with an active harness, prompt types when handling model I/O, and tool types when exposing application operations to the model. The same import block also includes error classes for tool validation and result availability, which is a signal that agent applications should handle failures as part of the public contract rather than relying on ad hoc exception shapes.

Sources: apps/docs/src/content/docs/api/agent-api.md

The page also makes clear that the Agent API includes integration points beyond local TypeScript functions. connectMcpServer and McpServerConnection expose Model Context Protocol connectivity, while bash, BashFactory, SandboxFactory, ShellOptions, and ShellResult belong to the harness side of the agent: controlled execution environments and shell access. MCP connections are different from local tools because they connect the agent to externally hosted tool servers, whereas defineTool describes model-callable capabilities implemented directly by the application. Both become part of the agent harness, but they have different deployment and authentication boundaries.

Sources: apps/docs/src/content/docs/api/agent-api.md

Relevant Source Files

• apps/docs/src/content/docs/api/agent-api.md — The first-party API reference for the Agent API. It declares the @flue/runtime import surface, documents defineAgentProfile(...), and lists the public types used for profiles, dispatch, sessions, prompts, tools, MCP, sandboxing, and shell execution.

Import Surface

A typical consumer imports Agent API members directly from @flue/runtime. The documented import list includes runtime errors such as FlueError, ResultUnavailableError, ToolInputValidationError, ToolLegacyDefinitionError, ToolOutputSerializationError, ToolOutputValidationError; helper functions such as bash, connectMcpServer, defineAgent, defineAgentProfile, defineTool, and dispatch; and many public types used to describe an agent’s configuration and runtime behavior. That concentration is intentional: the agent author should be able to define the harness, start work, model tool contracts, and type session behavior from a single package boundary.

Sources: apps/docs/src/content/docs/api/agent-api.md

The public type names show the main seams in the API. AgentProfile, AgentDefinition, AgentRuntimeConfig, and AgentInitializerContext describe the definition phase. AgentDispatchRequest, NamedAgentDispatchRequest, DispatchReceipt, CallHandle, TaskOptions, FlueSession, and FlueSessions describe invocation and durable session interaction. PromptOptions, PromptModel, PromptImage, PromptResponse, PromptResultResponse, PromptUsage, and ThinkingLevel describe model-facing prompt behavior. ToolDefinition, ToolContext, ToolInput, ToolOutput, schema types, and validation issue types describe the controlled action surface exposed to the model.

Sources: apps/docs/src/content/docs/api/agent-api.md

import {
  defineAgent,
  defineAgentProfile,
  defineTool,
  dispatch,
  connectMcpServer,
  bash,
  type AgentProfile,
  type AgentDispatchRequest,
  type FlueSession,
  type PromptOptions,
  type ToolDefinition,
} from '@flue/runtime';

Profiles and Agent Definitions

defineAgentProfile(profile: AgentProfile): AgentProfile validates and returns a reusable profile. A profile is a baseline agent description that can be used directly by an agent definition or registered as a named subagent available to session.task(). The documented validation behavior is important: profiles are rejected when they contain unknown fields, invalid capabilities, duplicate capability names, or circular subagents. That means profile composition is not only a TypeScript convenience; it is a runtime validation boundary that protects larger multi-agent configurations from ambiguous names and recursive delegation graphs.

Sources: apps/docs/src/content/docs/api/agent-api.md

An AgentProfile can include name, description, model, instructions, skills, tools, actions, and subagents. The name is required when selecting the profile with session.task(), while the description gives humans and surrounding application code a readable summary. The model field supplies the default model specifier. instructions are prepended to discovered workspace context, which places profile guidance before runtime context gathered by the harness. skills, tools, and actions expand the agent’s capabilities, and subagents make named delegated profiles available to the active session.

Sources: apps/docs/src/content/docs/api/agent-api.md

defineAgent is the author-facing companion to reusable profiles. The docs identify it as part of the same Agent API import surface, and first-party examples use it to return a complete harness object with a model, tools, skills, sandbox, and instructions. When you write an agent module, prefer keeping reusable defaults in profiles and using defineAgent to assemble the concrete resource that your application routes, channels, or CLI commands will invoke. This separation keeps shared role definitions portable while still letting a deployed agent bind target-specific details such as sandbox factories or runtime configuration.

Sources: apps/docs/src/content/docs/api/agent-api.md

Sessions, Dispatch, and Runtime Interaction

The Agent API separates defining an agent from starting or continuing work. dispatch and the dispatch request types are the public vocabulary for submitting work to an agent, while DispatchReceipt and CallHandle describe the handoff after the runtime accepts the request. This distinction matters in durable systems: callers should not assume that accepting work and producing a final result are the same event. A receipt can represent accepted work, while result access may involve waiting, streaming, polling, or handling ResultUnavailableError when a result is not yet ready or cannot be produced in the requested way.

Sources: apps/docs/src/content/docs/api/agent-api.md

Sessions are represented by FlueSession and FlueSessions. A session is the runtime container for an agent’s continuing work: prompts, delegated tasks, context, tools, skills, and durable state are coordinated through the harness rather than through one-off model calls. The exported TaskOptions and NamedAgentDispatchRequest names also indicate the two common interaction patterns: submit work to a particular agent resource, or delegate a task to a named profile that has been registered as a subagent. In both cases, the application should treat the session as the place where ongoing agent activity is coordinated.

Sources: apps/docs/src/content/docs/api/agent-api.md

Prompt-related types make model interaction explicit without forcing users to manually build provider-specific payloads everywhere. PromptOptions configures a prompt request, PromptModel and ThinkingLevel capture model selection and reasoning controls, PromptImage represents image input, and PromptResponse, PromptResultResponse, and PromptUsage describe returned content and usage accounting. These names frame prompts as structured interactions inside the harness, not raw strings passed to an LLM. That is consistent with Flue’s model of giving agents memory, tools, context, and execution capabilities around the model.

Sources: apps/docs/src/content/docs/api/agent-api.md

Tools, MCP, and Sandbox Components

Tools are the model-callable application operations registered with an agent. The Agent API exposes defineTool plus ToolDefinition, ToolContext, ToolInput, ToolOutput, ToolInputSchema, ToolOutputSchema, and ToolValidationIssue. The related error classes show the expected failure domains: invalid tool input, legacy tool definitions, output serialization problems, and output validation failures. Tool authors should therefore think in terms of schemas and serializable results. A tool is not just a callback; it is a validated contract between the model, the harness, and application code.

Sources: apps/docs/src/content/docs/api/agent-api.md

MCP support appears in the Agent API through connectMcpServer, McpServerConnection, and McpServerOptions. Use this path when an agent needs tools exposed by a Model Context Protocol server rather than tools implemented inside the same codebase. Local tools usually share the application’s deployment, secrets model, and TypeScript types. MCP tools may be managed separately and connected at runtime with their own options. A well-structured agent can combine both, but production applications should document which capabilities are local, which come from MCP, and how authentication is handled for each connection.

Sources: apps/docs/src/content/docs/api/agent-api.md

Sandbox and shell types are also part of the agent contract because autonomous work often requires controlled execution. The documented import surface includes bash, BashFactory, SandboxFactory, ShellOptions, ShellResult, FileStat, and FlueFs. These names describe the harness capabilities around filesystem access and shell execution. Application authors should configure sandbox behavior intentionally: shell access gives agents the ability to inspect files, run commands, or operate on generated artifacts, so it should be paired with clear instructions, safe defaults, and route-level authorization when exposed through HTTP or channels.

Sources: apps/docs/src/content/docs/api/agent-api.md

Compact Reference

Implementation Guidance and Next Steps

When adding an agent to a Flue application, start by deciding which parts are reusable and which are deployment-specific. Put role information, default model choice, instructions, skills, tools, actions, and subagent structure into an AgentProfile when those choices should be shared. Use defineAgent for the concrete harness that will be invoked by the runtime. Validate profile names carefully if you plan to call session.task(), because named subagents rely on stable profile names and the profile validator rejects duplicate capability names and circular subagent structures.

Sources: apps/docs/src/content/docs/api/agent-api.md

Next, design the interaction boundary. If callers only need to start work, use the dispatch-oriented types and handle receipts separately from final results. If your code is operating inside an active agent, use session and prompt types to preserve the harness abstraction. Add local tools with schemas when the capability belongs to your application, connect MCP servers when capability ownership lives elsewhere, and configure sandbox or shell access only when the agent needs to inspect, generate, or execute artifacts. For adjacent details, read the Tool API, Sandbox API, Routing API, and the durable execution guide.