Kikoyu Core API Reference / AgentBuilder

Class: AgentBuilder

Fluent builder for constructing validated Agent instances using method chaining.

Example

const agent = Agent.builder()
  .setName('Support Agent')
  .setInstructions('Help users resolve issues.')
  .setApiKey(process.env.KIKOYU_API_KEY)
  .addTool(myTool)
  .build();

Constructors

new AgentBuilder()

new AgentBuilder(): AgentBuilder

Returns

AgentBuilder

Methods

addTool()

addTool(tool): this

Attaches a single tool to the agent.

Parameters

tool

Tool

Tool definition.

Returns

this

Defined in

agent-builder.ts:72

addTools()

addTools(…tools): this

Attaches multiple tools to the agent.

Parameters

tools

…Tool<any, any, any>[]

Array of tool definitions.

Returns

this

Defined in

agent-builder.ts:81

build()

build(): Agent

Validates required configuration fields and builds an immutable Agent.

Returns

Agent

Throws

Error if name, instructions, or model are missing.

Defined in

agent-builder.ts:133

setApiKey()

setApiKey(apiKey): this

Convenience helper to set up OpenAIProvider / Kikoyu API Key.

Parameters

apiKey

string

API key string.

Returns

this

Defined in

agent-builder.ts:63

setInstructions()

setInstructions(instructions): this

Sets the system instructions / persona prompt.

Parameters

instructions

string

Detailed instructions for the agent.

Returns

this

Defined in

agent-builder.ts:45

setModel()

setModel(model): this

Configures the ModelProvider instance.

Parameters

model

ModelProvider

ModelProvider implementation (e.g. OpenAIProvider).

Returns

this

Defined in

agent-builder.ts:54

setName()

setName(name): this

Sets the agent’s display name.

Parameters

name

string

Non-empty string name for the agent.

Returns

this

Defined in

agent-builder.ts:36

withGuardrails()

withGuardrails(…guardrails): this

Attaches input or output guardrails to the agent.

Parameters

guardrails

…Guardrail<any>[]

Guardrail instances.

Returns

this

Defined in

agent-builder.ts:90

withHandoffs()

withHandoffs(…handoffs): this

Attaches handoffs to other target agents.

Parameters

handoffs

…(Agent | Handoff)[]

Handoff or target Agent instances.

Returns

this

Defined in

agent-builder.ts:99

withMaxHandoffs()

withMaxHandoffs(max): this

Sets maximum allowed agent handoffs before loop prevention triggers.

Parameters

max

number

Returns

this

Defined in

agent-builder.ts:116

withMaxRetries()

withMaxRetries(max): this

Sets maximum model retry attempts.

Parameters

max

number

Returns

this

Defined in

agent-builder.ts:124

withResponseSchema()

withResponseSchema(schema): this

Configures a Zod response schema for structured output.

Parameters

schema

any

Returns

this

Defined in

agent-builder.ts:108