nimgent/agent

This page is generated from the module’s exported API and ## documentation comments.

Reusable agent configuration and execution API.

This layer owns the generic model -> tool -> model run. Applications that need persistence, compaction, permissions, or presentation can keep those concerns outside the agent and use the lower-level nimgent APIs directly.

Types

Agent

The model and defaults are immutable by convention after construction.

Agent = ref object
  model*: LanguageModel
  instructions*: string
  tools*: seq[Tool]
  maxTokens*: int
  generationOptions*: GenerationOptions
  maxRetries*: int ## Maximum number of model turns. The agent defaults to a small bounded
                   ## loop so an accidental tool cycle cannot run forever.
  maxSteps*: int
  toolChoice*: ToolChoice
  providerOptions*: ProviderOptions
  approvalPolicy*: ToolApprovalPolicy

View source

Procedures

newAgent

Create a reusable agent. The returned agent is configuration; each run receives its own request and response state.

proc newAgent(model: LanguageModel; instructions = ""; tools: seq[Tool] = @[];
              maxTokens = 0; generationOptions = GenerationOptions();
              maxRetries = 2; maxSteps = 8; providerOptions = ProviderOptions();
              toolChoice = toolChoiceAuto();
              approvalPolicy: ToolApprovalPolicy = nil): Agent {.
    raises: [ProviderError], tags: [], forbids: [].}

Returns: Agent.

Arguments

Name	Type	Default
model	LanguageModel
instructions	inferred	""
tools	seq[Tool]	@[]
maxTokens	inferred	0
generationOptions	inferred	GenerationOptions()
maxRetries	inferred	2
maxSteps	inferred	8
providerOptions	inferred	ProviderOptions()
toolChoice	inferred	toolChoiceAuto()
approvalPolicy	ToolApprovalPolicy	nil

View source

runAsync

Run until the model finishes, no executable tool calls remain, or maxSteps is reached.

proc runAsync(agent: Agent; prompt = ""; messages: seq[Message] = @[];
              abort: AbortCheck = nil; callbacks = RunCallbacks();
              conversationId = ""; metadata: JsonNode = nil; turnId = ""): Future[
    ProviderResponse] {.stackTrace: false, raises: [Exception, ValueError,
    ProviderError, KeyError, CatchableError], tags: [RootEffect, TimeEffect],
                        forbids: [].}

Returns: Future[ProviderResponse].

Arguments

Name	Type	Default
agent	Agent
prompt	inferred	""
messages	seq[Message]	@[]
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()
conversationId	inferred	""
metadata	JsonNode	nil
turnId	inferred	""

View source

run

Blocking convenience wrapper around runAsync.

proc run(agent: Agent; prompt = ""; messages: seq[Message] = @[];
         abort: AbortCheck = nil; callbacks = RunCallbacks();
         conversationId = ""; metadata: JsonNode = nil; turnId = ""): ProviderResponse {.raises: [
    ValueError, Exception, OSError, ProviderError, KeyError, CatchableError],
    tags: [TimeEffect, RootEffect], forbids: [].}

Returns: ProviderResponse.

Arguments

Name	Type	Default
agent	Agent
prompt	inferred	""
messages	seq[Message]	@[]
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()
conversationId	inferred	""
metadata	JsonNode	nil
turnId	inferred	""

View source

streamAsync (overload 1)

Stream an agent run. onEvent receives normalized model deltas and may return false to cancel the run.

proc streamAsync(agent: Agent; prompt: string; onEvent: StreamCallback;
                 messages: seq[Message] = @[]; abort: AbortCheck = nil;
                 callbacks = RunCallbacks(); conversationId = "";
                 metadata: JsonNode = nil; turnId = ""): Future[ProviderResponse] {.
    stackTrace: false,
    raises: [Exception, ValueError, ProviderError, KeyError, CatchableError],
    tags: [RootEffect, TimeEffect], forbids: [].}

Returns: Future[ProviderResponse].

Arguments

Name	Type	Default
agent	Agent
prompt	string
onEvent	StreamCallback
messages	seq[Message]	@[]
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()
conversationId	inferred	""
metadata	JsonNode	nil
turnId	inferred	""

View source

stream (overload 1)

Blocking convenience wrapper around streamAsync.

proc stream(agent: Agent; prompt: string; onEvent: StreamCallback;
            messages: seq[Message] = @[]; abort: AbortCheck = nil;
            callbacks = RunCallbacks(); conversationId = "";
            metadata: JsonNode = nil; turnId = ""): ProviderResponse {.raises: [
    ValueError, Exception, OSError, ProviderError, KeyError, CatchableError],
    tags: [TimeEffect, RootEffect], forbids: [].}

Returns: ProviderResponse.

Arguments

Name	Type	Default
agent	Agent
prompt	string
onEvent	StreamCallback
messages	seq[Message]	@[]
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()
conversationId	inferred	""
metadata	JsonNode	nil
turnId	inferred	""

View source

runEventsAsync

Run an agent while receiving lifecycle events.

proc runEventsAsync(agent: Agent; prompt = ""; messages: seq[Message] = @[];
                    abort: AbortCheck = nil; callbacks = RunCallbacks();
                    conversationId = ""; metadata: JsonNode = nil; turnId = "";
                    onEvent: AgentEventCallback = nil): Future[ProviderResponse] {.
    stackTrace: false,
    raises: [Exception, ValueError, ProviderError, KeyError, CatchableError],
    tags: [RootEffect, TimeEffect], forbids: [].}

Returns: Future[ProviderResponse].

Arguments

Name	Type	Default
agent	Agent
prompt	inferred	""
messages	seq[Message]	@[]
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()
conversationId	inferred	""
metadata	JsonNode	nil
turnId	inferred	""
onEvent	AgentEventCallback	nil

View source

streamAsync (overload 2)

Stream an agent run while receiving lifecycle events.

proc streamAsync(agent: Agent; prompt: string; onEvent: AgentEventCallback;
                 messages: seq[Message] = @[]; abort: AbortCheck = nil;
                 callbacks = RunCallbacks(); conversationId = "";
                 metadata: JsonNode = nil; turnId = ""): Future[ProviderResponse] {.
    stackTrace: false,
    raises: [Exception, ValueError, ProviderError, KeyError, CatchableError],
    tags: [RootEffect, TimeEffect], forbids: [].}

Returns: Future[ProviderResponse].

Arguments

Name	Type	Default
agent	Agent
prompt	string
onEvent	AgentEventCallback
messages	seq[Message]	@[]
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()
conversationId	inferred	""
metadata	JsonNode	nil
turnId	inferred	""

View source

stream (overload 2)

Blocking convenience wrapper around the event-aware stream.

proc stream(agent: Agent; prompt: string; onEvent: AgentEventCallback;
            messages: seq[Message] = @[]; abort: AbortCheck = nil;
            callbacks = RunCallbacks(); conversationId = "";
            metadata: JsonNode = nil; turnId = ""): ProviderResponse {.raises: [
    ValueError, Exception, OSError, ProviderError, KeyError, CatchableError],
    tags: [TimeEffect, RootEffect], forbids: [].}

Returns: ProviderResponse.

Arguments

Name	Type	Default
agent	Agent
prompt	string
onEvent	AgentEventCallback
messages	seq[Message]	@[]
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()
conversationId	inferred	""
metadata	JsonNode	nil
turnId	inferred	""

View source

events

Start a pull-based event stream for an agent run.

proc events(agent: Agent; prompt: string; messages: seq[Message] = @[];
            abort: AbortCheck = nil; callbacks = RunCallbacks();
            conversationId = ""; metadata: JsonNode = nil; turnId = ""): AgentEventStream {.
    raises: [ProviderError, Exception, ValueError], tags: [RootEffect],
    forbids: [].}

Returns: AgentEventStream.

Arguments

Name	Type	Default
agent	Agent
prompt	string
messages	seq[Message]	@[]
abort	AbortCheck	nil
callbacks	inferred	RunCallbacks()
conversationId	inferred	""
metadata	JsonNode	nil
turnId	inferred	""

View source