Interface: AIAgentConfig<TBus, TConnector>

Makaio Framework / ai-adapters-core / AIAgentConfig

Interface: AIAgentConfig<TBus, TConnector>

Defined in: ../../../adapters/core/src/agent/types.ts:166

Configuration for creating an AIAgent instance.

Combines agent identity, runtime input, and factory functions. model/cwd are optional here - configFactory provides adapter defaults.

Extends

Omit<AgentIdentity, "adapterSessionId">.AgentRuntimeInput

Type Parameters

TBus

TBus extends ScopedBus<string> = ScopedBus<string>

The scoped bus type for this adapter

TConnector

TConnector extends AIAgentConnector<TBus> = AIAgentConnector<TBus>

The connector type (for proper factory return typing)

Properties

adapterBus

adapterBus: TBus

Defined in: ../../../adapters/core/src/agent/types.ts:190

Scoped bus for adapter-specific events

adapterId

adapterId: string

Defined in: ../../../adapters/core/src/agent/types.ts:26

Adapter instance identifier

Inherited from

AgentIdentity.adapterId

adapterName

adapterName: string

Defined in: ../../../adapters/core/src/agent/types.ts:28

Adapter type name (e.g., ‘claude-code’, ‘gemini-sdk’)

Inherited from

AgentIdentity.adapterName

adapterSessionId?

optional adapterSessionId?: string

Defined in: ../../../adapters/core/src/agent/types.ts:172

Adapter-specific session identifier for multi-turn conversations

agentId

agentId: string

Defined in: ../../../adapters/core/src/agent/types.ts:24

Unique agent identifier

Inherited from

AgentIdentity.agentId

allowedDirectories?

optional allowedDirectories?: string[]

Defined in: ../../../adapters/core/src/agent/types.ts:206

Directory restrictions for file-system tool execution.

allowedTools?

optional allowedTools?: string[]

Defined in: ../../../adapters/core/src/agent/types.ts:202

Allowed tool names (adapter-specific). Empty array = disable all tools.

availableModels?

optional availableModels?: object[]

Defined in: ../../../adapters/core/src/agent/types.ts:198

Available models for this adapter (used for context window lookup)

contextWindowSize

contextWindowSize: number

Maximum context window size in tokens.

family?

optional family?: string

Model family name (e.g., ‘opus’, ‘sonnet’, ‘gpt-4o’). Used for alias resolution and UI grouping.

friendlyName?

optional friendlyName?: string

Human-readable display name (e.g., ‘Sonnet 4.5’, ‘GPT-4o’).

labId

labId: string

Lab that created this model (e.g., ‘anthropic’, ‘openai’, ‘google’).

metadata?

optional metadata?: object

Supplementary metadata from rich provider APIs (pricing, capabilities, etc.). Not used for routing or adapter logic — purely informational.

metadata.capabilities?

optional capabilities?: object

Provider-scoped capabilities for this model offering.

metadata.capabilities.parallelToolCalls?

optional parallelToolCalls?: boolean

Whether multiple tool calls can be issued in a single turn.

metadata.capabilities.pdfUpload?

optional pdfUpload?: boolean

Whether the provider accepts PDF file uploads.

metadata.capabilities.speechToText?

optional speechToText?: object

Speech-to-text capability descriptor.

metadata.capabilities.speechToText.modes

modes: (… | …)[]

Supported transcription modes.

metadata.capabilities.speechToText.vocabularyBiasing?

optional vocabularyBiasing?: boolean

Whether the model supports vocabulary/terminology biasing. Optional by design because model metadata can be partial, unlike provider runtime capabilities.

metadata.capabilities.structuredOutput?

optional structuredOutput?: boolean

Whether the provider supports structured (JSON schema) output.

metadata.capabilities.textToSpeech?

optional textToSpeech?: object

Text-to-speech capability descriptor.

metadata.capabilities.textToSpeech.modes

modes: (… | …)[]

Supported synthesis modes.

metadata.capabilities.textToSpeech.outputFormats?

optional outputFormats?: …[]

Supported output audio formats. Optional because metadata may omit it.

metadata.capabilities.textToSpeech.voiceInstructions?

optional voiceInstructions?: boolean

Whether the model supports style/tone instructions (e.g., gpt-4o-mini-tts). Optional because metadata may omit it.

metadata.capabilities.textToSpeech.voiceSelection?

optional voiceSelection?: boolean

Whether the user can select a voice preset. Optional because model metadata may omit it.

metadata.capabilities.toolCalling?

optional toolCalling?: boolean

Whether the provider’s API supports tool/function calling.

metadata.capabilities.vision?

optional vision?: boolean

Whether the model accepts image inputs.

metadata.description?

optional description?: string

Optional description of the model *

metadata.includedInSubscription?

optional includedInSubscription?: boolean

Whether this model is included in the provider’s subscription plan.

metadata.maxOutputTokens?

optional maxOutputTokens?: number

Maximum output tokens the provider allows for this model.

metadata.pricing?

optional pricing?: object

Token pricing for this model offering.

metadata.pricing.request?

optional request?: object

Per-request pricing (GitHub Copilot premium requests, etc.).

metadata.pricing.request.multiplier

multiplier: number

Cost per request in provider billing units (0 = free).

metadata.pricing.token?

optional token?: object

Per-token pricing (Anthropic direct, OpenAI direct, etc.).

metadata.pricing.token.cacheWritePerMillion?

optional cacheWritePerMillion?: number

Cost per million cache-write input tokens (USD).

metadata.pricing.token.inputCachedPerMillion?

optional inputCachedPerMillion?: number

Cost per million cache-read input tokens (USD).

metadata.pricing.token.inputPerMillion

inputPerMillion: number

Cost per million input tokens (USD).

metadata.pricing.token.outputPerMillion

outputPerMillion: number

Cost per million output tokens (USD).

name

name: string

Model identifier used by the provider (e.g., ‘claude-sonnet-4-6’, ‘gpt-4o’, ‘gemini-2.5-pro’).

supportedReasoningLevels?

optional supportedReasoningLevels?: object

Maps supported reasoning levels to provider-native values. When omitted, the model does not support extended thinking / reasoning.

supportedReasoningLevels.extra-high?

optional extra-high?: string | number = reasoningLevelValue

supportedReasoningLevels.high?

optional high?: string | number = reasoningLevelValue

supportedReasoningLevels.low?

optional low?: string | number = reasoningLevelValue

supportedReasoningLevels.medium?

optional medium?: string | number = reasoningLevelValue

supportedReasoningLevels.none?

optional none?: string | number = reasoningLevelValue

capabilities

capabilities: string[]

Defined in: ../../../adapters/core/src/agent/types.ts:194

Adapter capabilities (e.g., [‘streaming’, ‘tools’, ‘vision’])

clientId?

optional clientId?: string

Defined in: ../../../adapters/core/src/agent/types.ts:186

Client identifier for the application this adapter belongs to (e.g., ‘claude-code’, ‘gemini’).

configFactory

configFactory: (input) => Promise<BaseAgentConnectorConfig<TBus, object> & object>

Defined in: ../../../adapters/core/src/agent/types.ts:229

Config factory - transforms partial input into full adapter-specific config. This is the seam where adapters inject their defaults (especially model).

Parameters

input

ConfigFactoryInput<TBus>

Returns

Promise<BaseAgentConnectorConfig<TBus, object> & object>

connectorFactory

connectorFactory: (config) => TConnector | Promise<TConnector>

Defined in: ../../../adapters/core/src/agent/types.ts:236

Connector factory - creates connector from full config. Called AFTER configFactory returns the complete configuration. Config includes adapterId (passed through from input by config factory).

Parameters

config

BaseAgentConnectorConfig<TBus, object> & object

Returns

TConnector | Promise<TConnector>

cwd?

optional cwd?: string

Defined in: ../../../adapters/core/src/agent/types.ts:40

Working directory for agent execution (optional - platform provides default)

Inherited from

AgentRuntimeInput.cwd

disallowedTools?

optional disallowedTools?: string[]

Defined in: ../../../adapters/core/src/agent/types.ts:204

Disallowed tool names (adapter-specific). Takes precedence over allowedTools.

env?

optional env?: Record<string, string>

Defined in: ../../../adapters/core/src/agent/types.ts:42

Environment variables to pass to agent execution

Inherited from

AgentRuntimeInput.env

ephemeral?

optional ephemeral?: boolean

Defined in: ../../../adapters/core/src/agent/types.ts:223

When true, PreUserMessage hooks are skipped for this agent. Use for ephemeral ping agents where session enrichment and context injection are not needed and would be actively harmful.

globalBus?

optional globalBus?: IMakaioBus

Defined in: ../../../adapters/core/src/agent/types.ts:188

Global bus instance (defaults to MakaioBus singleton)

harnessId?

optional harnessId?: string

Defined in: ../../../adapters/core/src/agent/types.ts:184

Resolved harness ID for tool policy lookup.

mcpSessionContext?

optional mcpSessionContext?: LedgerSessionContext

Defined in: ../../../adapters/core/src/agent/types.ts:211

MCP session context resolved by the orchestrator. Passed through to the connector config so adapters can inject direct tools.

model?

optional model?: string

Defined in: ../../../adapters/core/src/agent/types.ts:38

Model to use (optional - adapter provides default)

Inherited from

AgentRuntimeInput.model

nativeTools

nativeTools: string[]

Defined in: ../../../adapters/core/src/agent/types.ts:196

Native tools built into the adapter (e.g., [‘shell_command’, ‘apply_patch’])

providerContext?

optional providerContext?: object

Defined in: ../../../adapters/core/src/agent/types.ts:180

Unresolved provider context (credential refs, not plaintext). Set by the orchestrator before forwarding the startAgent request. Connectors resolve credentials locally via resolveConnectorCredentials().

credentialEnvVars?

optional credentialEnvVars?: Record<string, string>

Maps credential keys to environment variable names for subprocess adapters. E.g., { apiKey: 'ANTHROPIC_API_KEY' }.

credentialRefs

credentialRefs: Record<string, string & $brand<"CredentialRef">>

Credential references resolved at the connector layer, not on the bus.

definitionId

definitionId: string

Provider definition ID (e.g., 'anthropic', 'alibaba').

endpointOverrides?

optional endpointOverrides?: object

Endpoint URL overrides keyed by protocol.

endpointOverrides.anthropic?

optional anthropic?: string

endpointOverrides.openai?

optional openai?: string

providerConfigId

providerConfigId: string

Provider config UUID. Links back to the ProviderConfig that produced this context.

reasoningEffort?

optional reasoningEffort?: "none" | "low" | "medium" | "high" | "extra-high"

Defined in: ../../../adapters/core/src/agent/types.ts:44

Reasoning effort for supporting adapters

Inherited from

AgentRuntimeInput.reasoningEffort

resumeAdapterSessionId?

optional resumeAdapterSessionId?: string

Defined in: ../../../adapters/core/src/agent/types.ts:182

Previous adapter session ID for resume attempts (from recovery).

sessionId?

optional sessionId?: string

Defined in: ../../../adapters/core/src/agent/types.ts:174

Makaio session identifier

toolLedger?

optional toolLedger?: ISessionToolLedger

Defined in: ../../../adapters/core/src/agent/types.ts:216

Session-scoped ledger tracking MCP injection/discovery/call history. Created once per agent session and passed through unchanged on connector swaps.