import { type FuncType, type Token, type Type } from '@frontmcp/di'; import { type ConcurrencyConfig, type RateLimitConfig, type TimeoutConfig } from '@frontmcp/guard'; import { type EntryAvailability } from '@frontmcp/utils'; import { type AdapterType } from '../interfaces/adapter.interface'; import { type PluginType } from '../interfaces/plugin.interface'; import { type PromptType } from '../interfaces/prompt.interface'; import { type ProviderType } from '../interfaces/provider.interface'; import { type ResourceType } from '../interfaces/resource.interface'; import { type ToolType } from '../interfaces/tool.interface'; import { type ToolInputType, type ToolOutputType } from './tool.metadata'; /** * Agent type definition (class or factory function). * Used in app/plugin metadata for defining agents. */ export type AgentType = Type | FuncType | string; declare global { /** * Declarative metadata extends to the McpAgent decorator. * Extends ExtendFrontMcpToolMetadata so agents can use plugin metadata * options (e.g., cache, codecall) since agents are exposed as tools. * Uses interface for declaration merging support. */ interface ExtendFrontMcpAgentMetadata extends ExtendFrontMcpToolMetadata { } } /** * Supported LLM providers for the built-in adapter shorthand. */ export type AgentLlmProviderType = 'openai' | 'anthropic'; /** * Fallback configuration for withConfig. * - string[] = custom fallback paths to try in order * - false = disable fallbacks (direct lookup only) * - undefined = use auto-fallbacks based on entity context (default) */ export type WithConfigFallbacks = string[] | false; /** * Options for withConfig factory function. */ export interface WithConfigOptions { /** * Optional transform function to convert the raw config value. */ transform?: (value: unknown) => T; /** * Fallback paths to try if configPath not found. * - undefined: auto-generate based on entity context (default) * - string[]: use these specific paths in order * - false: no fallbacks, direct lookup only */ fallbacks?: WithConfigFallbacks; } /** * Helper type for resolving configuration from app config paths. * Supports automatic fallback resolution based on entity context. * * @example * ```typescript * // Auto-fallback: agents.my-agent.openaiKey → agents.openaiKey → openaiKey * withConfig('openaiKey') * * // Custom fallbacks * withConfig('apiKey', { fallbacks: ['custom.path', 'default.apiKey'] }) * * // Direct lookup only (no fallbacks) * withConfig('specificKey', { fallbacks: false }) * ``` */ export interface WithConfig { /** * Dot-notation path to resolve from app configuration. * @example 'llm.openai.apiKey' or 'agents.research.model' */ configPath: string; /** * Optional transform function to convert the raw config value. */ transform?: (value: unknown) => T; /** * Fallback paths to try if configPath not found. * - undefined: auto-generate based on entity context (default) * - string[]: use these specific paths in order * - false: no fallbacks, direct lookup only */ fallbacks?: WithConfigFallbacks; } /** * Factory function to create a WithConfig reference. * * @example * ```typescript * // Basic usage - auto-fallback based on entity context * apiKey: withConfig('openaiKey') * * // With transform * port: withConfig('dbPort', { transform: (v) => parseInt(v as string, 10) }) * * // Custom fallbacks * apiKey: withConfig('key', { fallbacks: ['custom.key', 'default.key'] }) * * // Disable fallbacks * apiKey: withConfig('exactPath.key', { fallbacks: false }) * ``` */ export declare function withConfig(configPath: string, options?: WithConfigOptions | ((value: unknown) => T)): WithConfig; /** * API key configuration - supports direct string, environment variable, or config path. */ export type AgentApiKeyConfig = string | { env: string; } | WithConfig; /** * Built-in provider shorthand configuration. * Use this for quick setup with standard LLM providers. * The SDK will auto-create the appropriate adapter. */ export interface AgentLlmBuiltinConfig { /** * LLM provider to use. */ provider: AgentLlmProviderType; /** * Model identifier (e.g., 'gpt-4-turbo', 'claude-3-opus'). */ model: string | WithConfig; /** * API key for the LLM provider. */ apiKey: AgentApiKeyConfig; /** * Optional base URL for custom/self-hosted endpoints. */ baseUrl?: string | WithConfig; /** * Default temperature for generations (0-2). */ temperature?: number; /** * Maximum tokens for responses. */ maxTokens?: number; } /** * Interface for LLM adapter (local type for use in metadata). * Full interface with same name defined in llm-adapter.interface.ts * This is intentionally a separate type to avoid circular dependencies. */ interface AgentLlmAdapterLocal { completion(prompt: unknown, tools?: unknown[], options?: unknown): Promise; streamCompletion?(prompt: unknown, tools?: unknown[], options?: unknown): AsyncGenerator; } /** * Direct adapter instance or factory configuration. * Use this for custom LLM integrations or complex setups. */ export interface AgentLlmAdapterConfig { /** * Direct adapter instance or factory function. * Factory receives ProviderRegistry for dependency injection. */ adapter: AgentLlmAdapterLocal | ((providers: unknown) => AgentLlmAdapterLocal); } /** * Combined LLM configuration type. * Supports built-in adapters, custom adapters, or DI token injection. * * Note: AgentLlmAdapter is defined in llm-adapter.interface.ts * Use Token here to avoid circular dependency; runtime validation * will check the adapter instance. */ export type AgentLlmConfig = AgentLlmBuiltinConfig | AgentLlmAdapterConfig | Token; /** * Configuration for agent swarm capabilities (agent-to-agent communication). */ export interface AgentSwarmConfig { /** * Whether this agent can see and invoke other agents as tools. * @default false (agents are isolated by default) */ canSeeOtherAgents?: boolean; /** * Explicit whitelist of agent IDs this agent can see. * If undefined and canSeeOtherAgents=true, sees all registered agents. */ visibleAgents?: string[]; /** * Whether this agent is visible to other agents. * @default true (agents are discoverable unless hidden) */ isVisible?: boolean; /** * Maximum depth for agent-to-agent calls (prevents infinite loops). * @default 3 */ maxCallDepth?: number; } /** * Configuration for agent execution behavior. */ export interface AgentExecutionConfig { /** * Maximum execution time in milliseconds. * @default 120000 (2 minutes) */ timeout?: number; /** * Maximum iterations for the agent loop. * @default 10 */ maxIterations?: number; /** * Enable streaming responses via SSE/WebSocket. * @default false */ enableStreaming?: boolean; /** * Enable MCP notifications for progress updates. * @default true */ enableNotifications?: boolean; /** * Interval for progress notifications in milliseconds. * @default 1000 */ notificationInterval?: number; /** * Whether to inherit parent scope's tools. * @default true */ inheritParentTools?: boolean; /** * Whether to execute tools through the call-tool flow (with plugins, hooks, authorization). * When true, tool calls go through the full MCP flow with all middleware. * When false, tools are executed directly for performance-critical scenarios. * @default true */ useToolFlow?: boolean; /** * Whether to inherit plugins from the parent scope. * When true, the agent's tools will benefit from standard plugin extensions * (e.g., cache, codecall) registered in the parent scope. * @default true */ inheritPlugins?: boolean; /** * Whether to automatically send progress notifications during agent execution. * When true, the agent sends notifications about LLM calls, tool executions, * and completion status via `notifications/progress` and `notifications/message`. * Requires `enableNotifications` to also be true. * @default false (opt-in feature) */ enableAutoProgress?: boolean; } /** * Configuration for exporting agent resources/prompts to parent scope. */ export interface AgentExportsConfig { /** * Resources to export to parent scope. * Use '*' to export all resources. */ resources?: ResourceType[] | '*'; /** * Prompts to export to parent scope. * Use '*' to export all prompts. */ prompts?: PromptType[] | '*'; /** * Providers to export to parent scope. */ providers?: ProviderType[]; } /** * Declarative metadata describing an autonomous Agent in FrontMCP. * * Agents are self-contained units with their own LLM provider, isolated scope * (tools, resources, prompts, providers, hooks), and the ability to be invoked * as tools by other agents or the parent app. * * @example * ```typescript * @Agent({ * name: 'research-agent', * description: 'Researches topics and compiles reports', * systemInstructions: 'You are a research assistant...', * llm: { * adapter: 'openai', * model: 'gpt-4-turbo', * apiKey: { env: 'OPENAI_API_KEY' }, * }, * tools: [WebSearchTool, SummarizeTool], * swarm: { canSeeOtherAgents: true }, * }) * export default class ResearchAgent extends AgentContext { ... } * ``` */ export interface AgentMetadata extends ExtendFrontMcpAgentMetadata { /** * Unique identifier for the agent. * Used for tool routing (use-agent:) and swarm discovery. * If omitted, derived from the class name or 'name' property. */ id?: string; /** * Human-readable name of the agent. * This becomes the base for the tool name when the agent is exposed as a tool. */ name: string; /** * Description of what the agent does. * Used in tool discovery and as context for LLM system instructions. */ description?: string; /** * System instructions for the agent. * Defines the agent's persona, capabilities, and behavior. */ systemInstructions?: string; /** * Zod schema for the agent's input (what triggers the agent). * Becomes the tool's inputSchema when agent is exposed as a tool. */ inputSchema?: InSchema; /** * Zod schema for the agent's output. * Becomes the tool's outputSchema when agent is exposed as a tool. */ outputSchema?: OutSchema; /** * LLM configuration for the agent. * Supports built-in adapters, custom adapters, or DI token injection. */ llm: AgentLlmConfig; /** * Agent-scoped providers (dependencies). */ providers?: ProviderType[]; /** * Agent-scoped plugins for additional capabilities. */ plugins?: PluginType[]; /** * Agent-scoped adapters for external integrations. */ adapters?: AdapterType[]; /** * Nested agents - agents inside this agent! * Nested agents are automatically registered as tools within the parent agent's scope. */ agents?: AgentType[]; /** * Agent-scoped tools available to the agent's LLM. */ tools?: ToolType[]; /** * Agent-scoped resources. */ resources?: ResourceType[]; /** * Agent-scoped prompts. */ prompts?: PromptType[]; /** * Resources, prompts, and providers to export to parent scope. */ exports?: AgentExportsConfig; /** * Swarm configuration for agent-to-agent communication. */ swarm?: AgentSwarmConfig; /** * Execution configuration. */ execution?: AgentExecutionConfig; /** * Tags for categorization and filtering. */ tags?: string[]; /** * Whether to hide this agent from discovery. * The agent can still be invoked by name if known. * @default false */ hideFromDiscovery?: boolean; /** * Rate limiting configuration for this agent. */ rateLimit?: RateLimitConfig; /** * Concurrency control configuration for this agent. */ concurrency?: ConcurrencyConfig; /** * Timeout configuration for this agent's execution. */ timeout?: TimeoutConfig; /** * Environment availability constraint. * When set, the agent is only discoverable and invocable in matching environments. * * @example Node.js only agent * ```typescript * @Agent({ name: 'deploy-agent', availableWhen: { runtime: ['node'] } }) * ``` */ availableWhen?: EntryAvailability; } /** * Zod schema for validating AgentMetadata at runtime. */ export declare const frontMcpAgentMetadataSchema: import("@frontmcp/lazy-zod").ZodObject<{ id: import("@frontmcp/lazy-zod").ZodOptional; name: import("@frontmcp/lazy-zod").ZodString; description: import("@frontmcp/lazy-zod").ZodOptional; systemInstructions: import("@frontmcp/lazy-zod").ZodOptional; inputSchema: import("@frontmcp/lazy-zod").ZodOptional>; outputSchema: import("@frontmcp/lazy-zod").ZodOptional; llm: import("@frontmcp/lazy-zod").ZodUnion; model: import("@frontmcp/lazy-zod").ZodUnion>; fallbacks: import("@frontmcp/lazy-zod").ZodOptional, import("@frontmcp/lazy-zod").ZodLiteral]>>; }, import("zod/v4/core").$strip>]>; apiKey: import("@frontmcp/lazy-zod").ZodUnion, import("@frontmcp/lazy-zod").ZodObject<{ configPath: import("@frontmcp/lazy-zod").ZodString; transform: import("@frontmcp/lazy-zod").ZodOptional>; fallbacks: import("@frontmcp/lazy-zod").ZodOptional, import("@frontmcp/lazy-zod").ZodLiteral]>>; }, import("zod/v4/core").$strip>]>; baseUrl: import("@frontmcp/lazy-zod").ZodOptional>; fallbacks: import("@frontmcp/lazy-zod").ZodOptional, import("@frontmcp/lazy-zod").ZodLiteral]>>; }, import("zod/v4/core").$strip>]>>; temperature: import("@frontmcp/lazy-zod").ZodOptional; maxTokens: import("@frontmcp/lazy-zod").ZodOptional; }, import("zod/v4/core").$strip>, import("@frontmcp/lazy-zod").ZodObject<{ adapter: import("@frontmcp/lazy-zod").ZodUnion, import("zod").ZodFunction]>; }, import("zod/v4/core").$strip>, import("zod").ZodCustom, import("zod").ZodCustom]>; providers: import("@frontmcp/lazy-zod").ZodOptional, Type>>>; plugins: import("@frontmcp/lazy-zod").ZodOptional, Type>>>; adapters: import("@frontmcp/lazy-zod").ZodOptional, Type>>>; agents: import("@frontmcp/lazy-zod").ZodOptional>>; tools: import("@frontmcp/lazy-zod").ZodOptional, string | Type>>>; resources: import("@frontmcp/lazy-zod").ZodOptional, Type>>>; prompts: import("@frontmcp/lazy-zod").ZodOptional, Type>>>; exports: import("@frontmcp/lazy-zod").ZodOptional, import("@frontmcp/lazy-zod").ZodLiteral<"*">]>>; prompts: import("@frontmcp/lazy-zod").ZodOptional, import("@frontmcp/lazy-zod").ZodLiteral<"*">]>>; providers: import("@frontmcp/lazy-zod").ZodOptional>; }, import("zod/v4/core").$strip>>; swarm: import("@frontmcp/lazy-zod").ZodOptional>; visibleAgents: import("@frontmcp/lazy-zod").ZodOptional>; isVisible: import("@frontmcp/lazy-zod").ZodDefault>; maxCallDepth: import("@frontmcp/lazy-zod").ZodDefault>; }, import("zod/v4/core").$strip>>; execution: import("@frontmcp/lazy-zod").ZodOptional>; maxIterations: import("@frontmcp/lazy-zod").ZodDefault>; enableStreaming: import("@frontmcp/lazy-zod").ZodDefault>; enableNotifications: import("@frontmcp/lazy-zod").ZodDefault>; notificationInterval: import("@frontmcp/lazy-zod").ZodDefault>; inheritParentTools: import("@frontmcp/lazy-zod").ZodDefault>; useToolFlow: import("@frontmcp/lazy-zod").ZodDefault>; inheritPlugins: import("@frontmcp/lazy-zod").ZodDefault>; enableAutoProgress: import("@frontmcp/lazy-zod").ZodDefault>; }, import("zod/v4/core").$strip>>; tags: import("@frontmcp/lazy-zod").ZodOptional>; hideFromDiscovery: import("@frontmcp/lazy-zod").ZodDefault>; rateLimit: import("@frontmcp/lazy-zod").ZodOptional>; partitionBy: import("@frontmcp/lazy-zod").ZodDefault, import("zod").ZodCustom<(ctx: { sessionId: string; clientIp?: string; userId?: string; }) => string, (ctx: { sessionId: string; clientIp?: string; userId?: string; }) => string>]>>>; }, import("zod/v4/core").$strip>>; concurrency: import("@frontmcp/lazy-zod").ZodOptional>; partitionBy: import("@frontmcp/lazy-zod").ZodDefault, import("zod").ZodCustom<(ctx: { sessionId: string; clientIp?: string; userId?: string; }) => string, (ctx: { sessionId: string; clientIp?: string; userId?: string; }) => string>]>>>; }, import("zod/v4/core").$strip>>; timeout: import("@frontmcp/lazy-zod").ZodOptional>; availableWhen: import("@frontmcp/lazy-zod").ZodOptional>; platform: import("@frontmcp/lazy-zod").ZodOptional>; runtime: import("@frontmcp/lazy-zod").ZodOptional>; deployment: import("@frontmcp/lazy-zod").ZodOptional>; provider: import("@frontmcp/lazy-zod").ZodOptional>; target: import("@frontmcp/lazy-zod").ZodOptional>; surface: import("@frontmcp/lazy-zod").ZodOptional>>; env: import("@frontmcp/lazy-zod").ZodOptional>; }, import("zod/v4/core").$strict>>; }, import("zod/v4/core").$loose>; export {}; //# sourceMappingURL=agent.metadata.d.ts.map