model

Documentation

Overview

Package model contains the core data types shared across react-agent and its sub-packages.

The types here are intentionally minimal and framework-agnostic so that the parent package imports only what it needs, and external adapters can convert to/from their own representations without depending on the orchestration logic.

Key types

• ToolDefinition — JSON-schema description of a function the LLM can call.
• ToolExecutor — interface for dispatching ToolCall slices to a backend.
• ContentItem — sealed discriminated union: Message, ToolCall, ToolResult.
• Event — a timestamped, authored entry in an [ExecutionContext] history.
• Request / Response — the exchange contract between Agent and [LLMClient].

Index

• type ContentItem
• type Event
• type Message
  • func (Message) Type() string
• type Request
• type Response
• type ToolCall
  • func (ToolCall) Type() string
• type ToolDefinition
• type ToolExecutor
• type ToolResult
  • func (ToolResult) Type() string

Types

type ContentItem

type ContentItem interface {
	Type() string
	// contains filtered or unexported methods
}

ContentItem is a closed discriminated union of all values that can appear in an Event. The unexported marker method prevents external packages from satisfying the interface, keeping type switches exhaustive.

type Event

type Event struct {
	ID          string        `json:"id"`
	ExecutionID string        `json:"execution_id"`
	Timestamp   time.Time     `json:"timestamp"`
	Author      string        `json:"author"` // "user" | "agent" | "tools"
	Content     []ContentItem `json:"content"`
}

Event is the atomic unit of history in an ExecutionContext. Author identifies the source: "user", "agent", or "tools". One event per step-participant — the LLM produces one agent event per Think, the tool runner produces one tools event per Act.

type Message

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

Message is a chat turn (system / user / assistant plain text).

func (Message) Type

func (Message) Type() string

type Request

type Request struct {
	Instructions string
	Events       []Event
	Tools        []ToolDefinition
	MaxTokens    int64
}

Request is the agent's view of a single LLM call. Events carries the full conversation history; the LLMClient translates each Event into the provider-specific message format.

type Response

type Response struct {
	Content []ContentItem
}

Response is the agent's view of a single LLM reply. Content contains either ToolCall items (when the model wants to act) or a single Message item with Role "assistant" (when the model has an answer).

type ToolCall

type ToolCall struct {
	ID        string          `json:"tool_call_id"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

ToolCall is a single tool invocation requested by the LLM.

func (ToolCall) Type

func (ToolCall) Type() string

type ToolDefinition

type ToolDefinition struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	// Parameters is a JSON Schema object describing the function arguments.
	// Example: map[string]any{"type": "object", "properties": {...}, "required": [...]}
	Parameters map[string]any `json:"parameters"`
	Strict     bool           `json:"strict,omitempty"`
}

ToolDefinition describes a function the LLM can invoke. This type is intentionally independent of any specific tool framework — convert from mcp-toolkit, langchain, or your own registry with a simple loop.

type ToolExecutor

type ToolExecutor interface {
	Execute(ctx context.Context, calls []ToolCall) ([]ToolResult, error)
}

ToolExecutor abstracts concurrent tool dispatch for the Agent. Implement this interface to connect any tool-running backend. The default adapter for mcp-toolkit is in the mcpadapter subpackage.

type ToolResult

type ToolResult struct {
	ID      string   `json:"tool_call_id"`
	Name    string   `json:"name"`
	Status  string   `json:"status"` // "success" | "error"
	Content []string `json:"content"`
}

ToolResult is the outcome of executing a ToolCall.

func (ToolResult) Type

func (ToolResult) Type() string