proxias

package module
v0.0.0-...-742da16 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

README

Proxias

Proxias

CI Go Reference Go version License

A Go SDK to develop AI agents easily. It orchestrates: it runs an agent's turns, executes the actions it asks for, keeps the trace of what happened, and streams it. Everything else is an extension point (how the agent thinks, what it can do, what it remembers, which model it runs on), and the SDK ships batteries for each.

Use it for:

  • chat apps: a person talks to an agent, turn by turn;
  • headless harnesses: agents that run unattended, reacting to events (alerts, probes, webhooks) with Agent.Watch;
  • multi-agent apps: the app orchestrates; an agent talks to another through an action of the app's;
  • serving an agent: as an OpenAI-compatible model, over Agent Protocol, or over plain HTTP.

Quick start

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/anthropics/anthropic-sdk-go"

	"github.com/morebec/proxias"
	agentanthropic "github.com/morebec/proxias/adapters/anthropic"
)

func main() {
	agent := &proxias.Agent{
		ID:           "ada",
		AgentPersona: proxias.AgentPersona{Name: "Ada", Role: "assistant"},
		ActionExecutor: proxias.SimpleActionExecutor{Actions: map[string]proxias.SimpleAction{
			"get_time": {
				ActionDescriptor: proxias.ActionDescriptor{ID: "get_time", Description: "Tells the current time."},
				RunFn: func(context.Context, proxias.Session, map[string]any) (proxias.ActionExecutionResult, error) {
					now := time.Now().Format(time.RFC3339)
					return proxias.ActionExecutionResult{ActionID: "get_time", Status: "completed", Data: map[string]any{"now": now}}, nil
				},
			},
		}},
	}
	llm := agentanthropic.NewLLM(anthropic.NewClient(), "claude-haiku-5-5") // its key: ANTHROPIC_API_KEY
	session := proxias.NewSession(proxias.NewMessageEvent(proxias.NewUserSource("john"), "What time is it?"))

	// Loop takes turns until the agent is done: here, a call of get_time, then the reply.
	stream, err := agent.Loop(context.Background(), session, proxias.NewReActStrategy(llm))
	if err != nil {
		panic(err)
	}
	session, err = stream.Collect() // or range over stream.Updates() for the events and chunks as they come
	if err != nil {
		panic(err)
	}
	fmt.Println(session.LastEvent().Text())
}

Concepts

  • Agent: who it is (AgentPersona, Biases), what it can do (ActionExecutor), what it remembers (Memory), and what wraps each of its turns (Middleware). It holds no session: one agent serves any number of them.
  • Session and events: a session is the immutable trace of an agent's experience, a list of Events: messages from people, agents and systems, thoughts, action requests and their results, anything the app appends. The app keeps it.
  • Invoke, Loop, Watch: Invoke takes one turn; Loop takes turns until the strategy says the agent is done (StopReasonEndTurn) or it took DefaultMaxTurns (StopReasonMaxTurns, not an error); Watch loops on each event of a channel. Each returns a SessionStream: the updates as they come (whole events, chunks of text), and the session.
  • CognitiveStrategy: how the agent thinks, one turn at a time, given an Invocation (the agent, its session, its memories). It asks the model, has the agent's ActionExecutor run the actions it decides on, and says when the agent is done. Write your own, or wrap one with an AgentMiddleware.
  • ActionExecutor: the agent's execution layer: the actions it describes (ActionDescriptor, with a JSON Schema of their parameters), and their execution. A failed action is a result the model sees, not an error.
  • MemoryProvider: the agent's memory beyond a session, as it is: Recall returns it as a string, which the agent tells in its prompt (NewAgentPrompt). How it is kept, and the actions that curate it, are the app's. Whose memory it is, is the provider's call: from the session, it can tell whom the agent deals with. Message history is not memory: it is the session, which the app keeps.
  • LLM and System1Model: the two model interfaces the strategies use. An LLM answers a request (LLMRequest, built from a session with NewLLMRequestFromSession) with text, thinking and tool calls. A System1Model answers questions about a state with calibrated probabilities (a choice, a score, a noul), as a fast discriminative model does.

Batteries included

  • Strategies (see docs/strategies.md):
    • NewReActStrategy (ReAct): one model call a turn, every action a tool.
    • NewReWOOStrategy (ReWOO): the model plans the whole task, the agent runs the plan, and the model answers from what it found: two calls a turn.
    • NewObservePlanExecuteStrategy (Observe-Plan-Execute): a plan the model revises after every step, from what the step found, then the answer.
    • NewAdaptiveStrategy (Adaptive): a StrategySelector chooses one of named candidate strategies for each task, and the task keeps to it.
  • Strategy selectors: LLMStrategySelector, in a single call, and System1StrategySelector, a System One model's choice kept above its threshold.
  • Prompts: every prompt is a field of what uses it, its default an exported constant to use or extend (DefaultReActPrompt, DefaultReWOOPlanPrompt, DefaultObservePlanExecutePlanPrompt, DefaultLLMStrategySelectionPrompt, and adapters.DefaultChoicePrompt...).
  • Models:
    • adapters/anthropic (Claude: thinking, caching, usage counting);
    • adapters/openai (Chat Completions);
    • adapters.LLMSystem1, an LLM as a System1Model.
  • Transports:
    • transports/agenthttp: an agent over HTTP, its updates streamed;
    • transports/openaihttp: agents as models of an OpenAI-compatible Chat Completions API;
    • transports/agentprotocolhttp: an agent over Agent Protocol.
  • Memory: MarkdownMemory, a MEMORY.md told whole at every turn (the agent-cli example rewrites it with an action of its own). Any other kind (per person, retrieval...) is a MemoryProvider of the app's.
  • Actions: SimpleActionExecutor, actions as Go functions.

Examples

  • examples/agent-cli: a chat in the terminal with an agent that reads and writes files, runs bash, and curates its memory (a MarkdownMemory) across runs.
  • examples/agentdemo: the shared setup of the examples, and their scripted models: agent-chat, agent-team (agents that delegate to each other) and agent-unattended (a headless agent on probe events) run on it, without a key.
  • examples/agentbench: compares the strategies on scenarios, on scripts or on Claude: success, calls, tokens, cost, time.

Design principles

  • The SDK orchestrates; it never compensates for the model. What the model sees is the session as it is; what it answers is acted on as it is. Judgment is the model's.
  • Vendor quirks live in the adapters. What a vendor's API refuses or requires is that adapter's concern, not the strategies'.
  • The loop is outside the strategy. A strategy takes one turn; Loop and Watch decide when to take another.
  • Everything is replaceable. Strategies, selectors, prompts, executors, memory and models are interfaces or fields, with defaults.

Documentation

Overview

Package proxias is an SDK of agents that live through events rather than chat messages.

An Event is an entry of an agent's experience: a message from a person, another agent or a system (an instruction is a message from a system source), a thought, an action it requests, the result of one, anything the app appends for it. A Session is the trace of those events, kept by the app, like the conversation of a chat completions API. An Agent is who it is, its execution layer (ActionExecutor) and the AgentMiddleware that wraps every turn it takes.

How an agent thinks is a CognitiveStrategy, one turn at a time: NewReActStrategy (one model call a turn, every action a tool), NewReWOOStrategy (a plan of the whole task, its steps run, then the answer), and NewObservePlanExecuteStrategy (a plan revised after every step), or the app's own. NewAdaptiveStrategy chooses one of them for each task, with a StrategySelector (LLMStrategySelector, or System1StrategySelector). Each prompt is a field of what uses it, its default an exported constant (DefaultReActPrompt...). Strategies are vendor-neutral over two model interfaces: LLM, and System1Model (a System One model: questions about a state, answered with probabilities), which adapters implement.

Agent.Invoke takes one turn, Agent.Loop takes turns until one completes, executing the actions requested between them, and Agent.Watch Loops on each event of a channel. Each returns a SessionStream (whole events, and chunks of text as it is written); SessionStream.Collect reads it to its end. How agents talk to each other is the app's: an action of its own that invokes another agent.

Index

Constants

View Source
const DefaultLLMStrategySelectionPrompt = `` /* 890-byte string literal not displayed */

DefaultLLMStrategySelectionPrompt is the system prompt of an LLMStrategySelector, before who the agent is and what it can choose from, when its Prompt is empty.

View Source
const DefaultMaxTurns = 8

DefaultMaxTurns default value for the maximum number of turns Agent.Loop can perform.

View Source
const DefaultObservePlanExecutePlanPrompt = `` /* 1407-byte string literal not displayed */

DefaultObservePlanExecutePlanPrompt is the system prompt of the Observe-Plan-Execute strategy's plan, before who the agent is, the inventory of its actions and what the steps of the task found so far, when its PlanPrompt is empty.

View Source
const DefaultObservePlanExecuteReportPrompt = `` /* 707-byte string literal not displayed */

DefaultObservePlanExecuteReportPrompt is the system prompt of the Observe-Plan-Execute strategy's answer, before who the agent is and what the steps of the task found, when its ReportPrompt is empty.

View Source
const DefaultReActPrompt = `` /* 622-byte string literal not displayed */

DefaultReActPrompt is the system prompt of the ReAct strategy, before who the agent is, when its Prompt is empty.

View Source
const DefaultReWOOPlanPrompt = `` /* 1200-byte string literal not displayed */

DefaultReWOOPlanPrompt is the system prompt of the ReWOO strategy's plan, before who the agent is and the inventory of its actions, when its PlanPrompt is empty.

View Source
const DefaultReWOOSolvePrompt = `` /* 724-byte string literal not displayed */

DefaultReWOOSolvePrompt is the system prompt of the ReWOO strategy's answer, before who the agent is and the plan with what each step found, when its SolvePrompt is empty.

View Source
const DefaultStreamBufferSize = 16

DefaultStreamBufferSize is the updates a SessionStream holds that its reader has not read yet: the agent's turn goes on while they wait, and blocks once they are this many.

View Source
const DefaultSystem1SelectionThreshold = 0.5

DefaultSystem1SelectionThreshold is the confidence under which a System1StrategySelector chooses no strategy, when its SelectionThreshold is nil.

View Source
const DefaultSystem1StrategyChoiceInstructions = `` /* 175-byte string literal not displayed */

DefaultSystem1StrategyChoiceInstructions are the instructions of the choice a System1StrategySelector asks for, when its ChoiceInstructions is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActionDescriptor

type ActionDescriptor struct {
	// ID is the unique identifier of the action.
	ID string `json:"id"`
	// Name is a human friendly name, for display purposes.
	Name string `json:"name"`
	// Description is what the action does: the agent chooses among the actions
	// with it.
	Description string `json:"description"`
	// InputSchema is the JSON Schema of the action's parameters, if it has any.
	InputSchema map[string]any `json:"schema,omitempty"`
}

ActionDescriptor describes an action to whatever chooses among them (a model, a classifier): what it is called, what it does and how it is called (its InputSchema).

type ActionExecutionRequest

type ActionExecutionRequest struct {
	// ActionID is the ID of the action to run.
	ActionID string `json:"action_id"`
	// Params are the values of the action's parameters, by name, as its
	// InputSchema describes them.
	Params map[string]any `json:"params,omitempty"`
}

ActionExecutionRequest asks to run an action: the payload of an action request.

type ActionExecutionResult

type ActionExecutionResult struct {
	// ActionID is the action that ran.
	ActionID string `json:"action_id"`
	// ExecutionID identifies this execution of the action, to track it when it
	// runs
	// asynchronously.
	ExecutionID string `json:"execution_id,omitempty"`
	// Status tells how it went, in the executor's own vocabulary ("completed",
	// "failed", "running"...).
	Status string `json:"status"`
	// Data is the output of the action, or why it failed.
	Data map[string]any `json:"data,omitempty"`
}

ActionExecutionResult is what an action answered after being executed: the payload of an action result.

type ActionExecutor

type ActionExecutor interface {
	// Descriptors describes the actions.
	Descriptors(context.Context, Session) ([]ActionDescriptor, error)

	// Execute runs the actions, and returns exactly one result per execution
	// request, in order.
	Execute(context.Context, Session, []ActionExecutionRequest) ([]ActionExecutionResult, error)
}

ActionExecutor is the agent's execution layer: it describes the actions the agent can do, and runs them. Strategies only ask it for the descriptors and have the agent execute what they request; they never narrow it.

It returns an error when it fails itself (a registry or a queue that is down, an action it does not know...). An action that cannot run for a reason the agent should hear of is not such an error: its result has a failing Status, and Data that says why.

type AdaptiveCognitiveStrategy

type AdaptiveCognitiveStrategy struct {
	Selector   StrategySelector
	Candidates []StrategyCandidate
	// Default is the name of the candidate of a task the selector chooses no
	// candidate for: the first candidate when empty.
	Default string
}

AdaptiveCognitiveStrategy is the adaptive strategy: a selector chooses, for each task, the strategy that suits it among named candidates, and the task is that strategy's.

A turn has two phases:

  • choose: when the turn follows an outside event (a person's message, a probe, a system's message, an event of another agent: anything but the agent's own events and the results of its actions), the selector chooses a candidate from the session, and the choice is yielded as a thought of the agent ({"strategy":"rewoo"}). The turns that follow the agent's own events, until the next outside event, keep to the strategy the session records: a task is one strategy's from start to end.
  • delegate: the turn is the chosen strategy's.

So it costs the selector's call once a task, on top of the chosen strategy's own calls: next to nothing with a System One selector, one small model call with an LLM one. It suits agents that meet tasks of different shapes (a question to answer, a lookup chained to an email, a task that must adapt), each handled by the strategy that fits it. Its trade-off is that a wrong choice holds for the whole task; when the selector chooses none, the task is the default strategy's.

func NewAdaptiveStrategy

func NewAdaptiveStrategy(selector StrategySelector, candidates ...StrategyCandidate) AdaptiveCognitiveStrategy

NewAdaptiveStrategy returns the adaptive strategy of the selector and the candidates, the first one its default.

func (AdaptiveCognitiveStrategy) Invoke

Invoke takes one turn of the task: the strategy the session records for it, or, after an outside event, the one the selector chooses.

type Agent

type Agent struct {
	// ID identifies the agent: its events come from NewAgentSource(ID).
	ID string

	AgentPersona

	Biases []AgentBias

	ActionExecutor ActionExecutor

	// Memory is the agent's memory beyond a session, nil for none: each turn is
	// told what it recalls.
	Memory MemoryProvider

	// Middleware wrap every turn of the agent, whatever the strategy, the first
	// outermost.
	Middleware []AgentMiddleware
}

Agent is an agent: who it is, what it can do (its execution layer, ActionExecutor), and what wraps every turn it takes (AgentMiddleware). How it thinks is the strategy it is invoked with. It holds no session: the app keeps the session, so one Agent serves any number of them, concurrently.

func (*Agent) AsSource

func (a *Agent) AsSource() EventSource

AsSource returns an EventSource representing this agent.

func (*Agent) Invoke

func (a *Agent) Invoke(ctx context.Context, s Session, strategy CognitiveStrategy) (*SessionStream, error)

Invoke has the agent take one turn, with the strategy, on what happened last in the session (the caller appended it), which seeds the stream. It fails at once, without a stream, for no strategy.

func (*Agent) Loop

func (a *Agent) Loop(ctx context.Context, s Session, strategy CognitiveStrategy) (*SessionStream, error)

Loop has the agent take turns (Invoke), with the strategy, until its strategy says the agent stopped (StopReasonEndTurn, StopReasonLength, StopReasonContentFilter). A turn without a StopReason has the agent take another, to reason on what it added, until it took its turns: then its last update says StopReasonMaxTurns, which is not an error. It takes no new turn once ctx ends. It fails at once, without a stream, for no strategy.

func (*Agent) Watch

func (a *Agent) Watch(
	ctx context.Context,
	s Session,
	events <-chan Event,
	strategy CognitiveStrategy,
) (*SessionStream, error)

Watch has the agent Loop on each event of events, one at a time: the event is appended to the session, then a Loop runs. It closes when events is closed or ctx ends; an error of a loop is streamed, and the next event still comes. The stream's StopReason is that of the last event's loop. It fails at once, without a stream, for no strategy or no events.

type AgentBias

type AgentBias string

AgentBias is a bias the agent reasons with, in words (e.g. "prefer asking before acting").

type AgentMiddleware

type AgentMiddleware func(next CognitiveStrategy) CognitiveStrategy

AgentMiddleware wraps every turn of an agent, whatever the strategy (Agent.Middleware): it may add to the session it is given (an event, a system message), change or filter what the turn adds, time it, guard it...

type AgentPersona

type AgentPersona struct {
	Name  string
	Role  string
	Goals []string
}

AgentPersona is who the agent is.

type CognitiveStrategy

type CognitiveStrategy interface {
	Invoke(ctx context.Context, inv Invocation) iter.Seq[StreamUpdate]
}

CognitiveStrategy is how an agent thinks, one turn at a time for the given strategy. Within its turn it may call models and have the agent execute actions (Agent.Execute); it asks the agent's ActionExecutor for the descriptors, and never narrows them. Its prompts are its own.

type Event

type Event struct {
	ID EventID
	// ParentID is the event this one follows in the session, "" for the first.
	ParentID EventID
	// CausationID is the event that caused this one: the action request of an
	// action result.
	CausationID EventID
	Type        EventType
	Source      EventSource
	Payload     []byte
	Date        time.Time
}

Event is an entry of the agent's experience: something it perceived, thought, intended or said. Events are chained with ParentID, the event they follow, forming a reasoning trace.

func NewActionExecutionRequestEvent

func NewActionExecutionRequestEvent(source EventSource, req ActionExecutionRequest) (Event, error)

NewActionExecutionRequestEvent returns the event of the request, of the source: an error when its params are not JSON.

func NewActionExecutionResultEvent

func NewActionExecutionResultEvent(source EventSource, res ActionExecutionResult) (Event, error)

NewActionExecutionResultEvent returns the event of the result, of the source: an error when its data is not JSON.

func NewEvent

func NewEvent(t EventType, source EventSource, payload []byte) Event

NewEvent returns an event of a new ID, dated now.

func NewEventsFromLLMMessage

func NewEventsFromLLMMessage(currentAgentSource EventSource, m LLMMessage) []Event

NewEventsFromLLMMessage creates the events a message of the model of the current agent is, in its session: its thinking as thoughts, then its text, then its tool calls as action requests (of the calls' IDs). Its text is a message; with tool calls, it is a thought (text with tool calls is what the model thinks), left out when empty. The mirror of NewLLMMessageFromEvent.

func NewMessageEvent

func NewMessageEvent(source EventSource, text string) Event

NewMessageEvent returns a message of the source.

func NewThoughtEvent

func NewThoughtEvent(source EventSource, chunk LLMChunk) Event

NewThoughtEvent returns the event of the model's thinking, of the source, kept whole (its thinking and signature, or its redacted thinking), to be given back as it came.

func (Event) HasSourceType

func (e Event) HasSourceType(t EventSourceType) bool

HasSourceType tells whether the event comes from a source of the type.

func (Event) Text

func (e Event) Text() string

Text is the payload as text.

type EventID

type EventID string

EventID identifies an event.

type EventSource

type EventSource struct {
	Type     EventSourceType
	ID       string
	Metadata string
}

EventSource indicates from where an event originated. This can be a user, an agent, a tool call, a system's state, etc.

func NewAgentSource

func NewAgentSource(id string) EventSource

NewAgentSource is the agent id.

func NewSystemSource

func NewSystemSource(id string) EventSource

NewSystemSource is the system id.

func NewUserSource

func NewUserSource(id string) EventSource

NewUserSource is the person id.

func (EventSource) String

func (s EventSource) String() string

String is the source as "type:id", then ":metadata" when there is some.

type EventSourceType

type EventSourceType string

EventSourceType is the kind of source an event comes from.

const (
	// EventSourceTypeUser is a person.
	EventSourceTypeUser EventSourceType = "user"
	// EventSourceTypeAgent is an agent: the one cogitating, or another.
	EventSourceTypeAgent EventSourceType = "agent"
	// EventSourceTypeSystem is anything else: an action runner, a clock, a
	// probe...
	EventSourceTypeSystem EventSourceType = "system"
)

type EventType

type EventType string

EventType is what an event is to the agent: a message, a thought, an action it requests, the result of one...

const (
	// EventTypeMessage represents a message sent by a given source.
	EventTypeMessage EventType = "message"

	// EventTypeThought represents a thought emitted by an event source (mostly
	// agents for chain of thought).
	EventTypeThought EventType = "cognition.thought"

	// EventTypeActionRequest is an action the agent asks its execution layer
	// for. Its payload is an
	// ActionExecutionRequest, as JSON.
	EventTypeActionRequest EventType = "action.request"

	// EventTypeActionResult is the result of an action request, its CausationID
	// the ID of the request. Its payload is
	// an ActionExecutionResult, as JSON.
	EventTypeActionResult EventType = "action.result"
)

type Invocation

type Invocation struct {
	Agent   Agent
	Session Session
}

Invocation is what a turn is given: the agent and its session. What the agent remembers, NewAgentPrompt recalls.

func (Invocation) LastEvent

func (inv Invocation) LastEvent() Event

LastEvent is the last event of the invocation's session.

type LLM

type LLM interface {
	Complete(ctx context.Context, req LLMRequest) iter.Seq2[LLMChunk, error]
}

LLM is a language model, as every strategy sees it: given a conversation (its instructions as system messages) and tools, it streams text and tool calls. A vendor adapter implements it (anthropic.NewLLM); a script implements it for tests.

type LLMChunk

type LLMChunk struct {
	Text             string
	ThinkingDelta    string `json:",omitempty"`
	ToolCall         *LLMToolCall
	Thinking         string
	Signature        string
	RedactedThinking string
	StopReason       StopReason `json:",omitempty"`
}

LLMChunk is a piece of what an LLM streams: a piece of text, a piece of thinking as the model writes it (ThinkingDelta, only to be shown: the whole block follows), a whole tool call, or a whole block of thinking (Thinking and its Signature, or RedactedThinking), which is to be given back as it came. When the model stopped (it did not ask for tool calls), the last chunk says why (StopReason), and only that.

type LLMMessage

type LLMMessage struct {
	// ID is the ID of the event of the message's text, when it is known: the
	// event its streamed chunks are pieces of.
	ID    EventID `json:",omitempty"`
	Role  LLMMessageRole
	Parts []LLMPart
}

LLMMessage is a message of a conversation with a model.

func NewLLMMessageFromEvent

func NewLLMMessageFromEvent(currentAgentSource EventSource, e Event) LLMMessage

NewLLMMessageFromEvent creates the message an event is, in the conversation of the model of the current agent: its own events are the assistant's, action results the tool's, a system's messages (its instructions) the system's, a person's messages the user's, and everything else (another agent's events, a system's observations) the user's, tagged with its type and source.

type LLMMessageRole

type LLMMessageRole string

LLMMessageRole is who says a message of a conversation with a model.

const (
	// LLMMessageRoleSystem is the instructions: the strategy's, and the
	// messages of a system source.
	LLMMessageRoleSystem LLMMessageRole = "system"
	// LLMMessageRoleUser is everything that happened to the agent.
	LLMMessageRoleUser LLMMessageRole = "user"
	// LLMMessageRoleAssistant is the agent.
	LLMMessageRoleAssistant LLMMessageRole = "assistant"
	// LLMMessageRoleTool is the results of the agent's tool calls.
	LLMMessageRoleTool LLMMessageRole = "tool"
)

type LLMPart

type LLMPart struct {
	Text             string
	ToolCall         *LLMToolCall
	ToolResult       *LLMToolResult
	Thinking         string
	Signature        string
	RedactedThinking string
}

LLMPart is a part of a message: text, a tool call, a tool's result, or the model's thinking (Thinking and its Signature, or RedactedThinking), given back as the model gave it.

type LLMRequest

type LLMRequest struct {
	// Messages is the conversation, oldest first. The system messages that open
	// it are the instructions: the stable ones first, so that a model can cache
	// them.
	Messages []LLMMessage

	// Tools are the actions the model may call, with their JSON Schemas.
	Tools []ActionDescriptor
}

LLMRequest is what an LLM is asked.

func NewLLMRequestFromSession

func NewLLMRequestFromSession(currentAgentSource EventSource, s Session) LLMRequest

NewLLMRequestFromSession creates an LLMRequest from a session.

type LLMStrategySelector

type LLMStrategySelector struct {
	LLM LLM
	// Prompt is the system prompt: DefaultLLMStrategySelectionPrompt when empty.
	Prompt string
}

LLMStrategySelector is a StrategySelector relying on an LLM: the model reads the candidates' names and descriptions, the agent's actions (their names and descriptions) and the conversation, and answers the name of one.

func (LLMStrategySelector) Select

func (s LLMStrategySelector) Select(
	ctx context.Context,
	inv Invocation,
	candidates []StrategyCandidate,
) (string, error)

Select asks the model.

type LLMToolCall

type LLMToolCall struct {
	ID    string
	Name  string
	Input map[string]any
}

LLMToolCall is a model's call of a tool: an action request.

type LLMToolResult

type LLMToolResult struct {
	CallID  string
	Content string
}

LLMToolResult is the result of a tool call: an action result.

type MarkdownMemory

type MarkdownMemory struct {
	// Path is the document's file.
	Path string
}

MarkdownMemory is a memory in one markdown document (a MEMORY.md), recalled whole at every turn.

func (MarkdownMemory) Recall

Recall returns the document, "" when it is missing.

type MemoryProvider

type MemoryProvider interface {
	// Recall returns what the agent remembers for the invocation, "" for
	// nothing. The invocation's session says who the agent deals with.
	Recall(ctx context.Context, inv Invocation) (string, error)
}

MemoryProvider is an agent's memory beyond a session: what it remembers for a turn, as it is. The agent tells it in its prompt (NewAgentPrompt). How it is kept, and the actions that curate it, are the app's.

type ObservePlanExecuteCognitiveStrategy

type ObservePlanExecuteCognitiveStrategy struct {
	LLM LLM
	// PlanPrompt is the system prompt of the plan:
	// DefaultObservePlanExecutePlanPrompt when empty.
	PlanPrompt string
	// ReportPrompt is the system prompt of the answer:
	// DefaultObservePlanExecuteReportPrompt when empty.
	ReportPrompt string
}

ObservePlanExecuteCognitiveStrategy is the Observe-Plan-Execute strategy: the model keeps a written plan of the task, and revises it after every step, from what the step found.

A turn is one phase, and Agent.Loop runs them in turn:

  • observe and plan: one model call, given the agent's actions and what the steps of the task found so far, writes the plan of the steps left. The plan is yielded as a thought of the agent, kept in the session. When no step is left, the turn reports instead.
  • execute: when the agent's last event is its plan, the agent runs the plan's first step, and yields its request and its result.
  • report: one model call writes the answer from the session and what the steps found. It is streamed, and ends the task.

So a task of N steps takes about N + 2 model calls: a plan before each step, the last one empty, and the answer. It suits longer tasks that must adapt to what they find (a lookup that comes back empty, a step that fails) while keeping to a plan. Its trade-off is a planning call per step: ReWOO, which never re-plans, takes two calls whatever the number of steps, and ReAct, which keeps no plan, one call per step.

func NewObservePlanExecuteStrategy

func NewObservePlanExecuteStrategy(llm LLM) ObservePlanExecuteCognitiveStrategy

NewObservePlanExecuteStrategy returns the Observe-Plan-Execute strategy of the model.

func (ObservePlanExecuteCognitiveStrategy) Invoke

Invoke takes one phase of the task: the next step of the agent's plan when its last event is that plan, otherwise a plan of the steps left, or the report when none is left.

type Prompt

type Prompt struct {
	// contains filtered or unexported fields
}

Prompt builds the text of a prompt for an LLM from paragraphs, titled sections and bullet points, so that the components that talk to a model do not assemble strings by hand. The text is plain Markdown: a section is a "## " heading, a bullet point a "- " line.

Blocks come out in the order they were added. Consecutive bullet points, and bullet points that follow a section, are on consecutive lines (a bullet point list belongs to the section above it); everything else is separated by a blank line. A Prompt is not safe for concurrent use. Use NewPrompt; its methods return the Prompt, to chain them.

func NewAgentPrompt

func NewAgentPrompt(ctx context.Context, inv Invocation) (*Prompt, error)

NewAgentPrompt returns a prompt describing is who the agent is, in words, for a strategy that tells a model: its source, then its name, role, goals and biases, those it has. Every premade strategy tells its models this, so that they are compared on the same context.

func NewPrompt

func NewPrompt() *Prompt

NewPrompt makes an empty Prompt.

func (*Prompt) AddBulletPoint

func (p *Prompt) AddBulletPoint(text string) *Prompt

AddBulletPoint adds a bullet point. A blank text is ignored. The lines of a text that has several are indented under its bullet.

func (*Prompt) AddLabeledBulletPoint

func (p *Prompt) AddLabeledBulletPoint(label, text string) *Prompt

AddLabeledBulletPoint adds a bullet point of the form "- label: text", to list things that have a name (an identifier, a term) along with what they are. A blank label is ignored, and a blank text leaves only the label.

func (*Prompt) AddLine

func (p *Prompt) AddLine(line string) *Prompt

AddLine adds a line, right under the block before it unless that is a paragraph. A blank line is ignored.

func (*Prompt) AddParagraph

func (p *Prompt) AddParagraph(text string) *Prompt

AddParagraph adds text as is. A blank text is ignored.

func (*Prompt) AddSection

func (p *Prompt) AddSection(title, content string) *Prompt

AddSection adds a section: a title, and its content, if any. Bullet points added right after it are part of the section. A blank title is ignored.

func (*Prompt) String

func (p *Prompt) String() string

String renders the prompt.

type ReActCognitiveStrategy

type ReActCognitiveStrategy struct {
	LLM          LLM
	SystemPrompt string
}

ReActCognitiveStrategy is the ReAct strategy (Reason and Act): the model thinks and acts in turns, deciding each step after it sees the last one's result.

A turn has two phases:

  • reason: one model call, given who the agent is, the session, and every action of the agent as a tool with its schema; its text is streamed.
  • act: when the model called tools, the agent runs them, all in one execution, and the turn ends with their results, for the next turn to reason on. When it called none, its answer is the reply.

So a task of N dependent steps takes about N + 1 model calls, each reading the whole conversation again. It suits open-ended tasks and conversations, where the next step depends on what the last one found. Its trade-off is the cost of that adaptivity: ReWOO, which plans the steps up front, takes two calls whatever their number, but never sees a result before the answer.

func NewReActStrategy

func NewReActStrategy(llm LLM) ReActCognitiveStrategy

NewReActStrategy returns the ReAct strategy of the model: a turn is one call, given who the agent is, the session as a conversation, and every action of the agent as a tool with its schema. When the model calls tools, the turn has the agent's execution layer run them, and ends with their results, for the next turn to reason on (no StopReason: the agent goes on); otherwise it ends with the agent's reply (StopReasonEndTurn). The text is streamed as it comes.

func (ReActCognitiveStrategy) Invoke

Invoke takes one ReAct turn: the model reasons, then the agent acts on the tools it called.

type ReWOOCognitiveStrategy

type ReWOOCognitiveStrategy struct {
	LLM LLM
	// PlanPrompt is the system prompt of the plan: DefaultReWOOPlanPrompt when
	// empty.
	PlanPrompt string
	// SolvePrompt is the system prompt of the answer: DefaultReWOOSolvePrompt
	// when empty.
	SolvePrompt string
}

ReWOOCognitiveStrategy is the ReWOO strategy (Reasoning WithOut Observation): the model plans the whole task up front, the agent runs the plan without asking the model again, and the model then writes the answer from what the plan found.

A turn has three phases:

  • plan: one model call, given the agent's actions, writes the plan as steps, each an action with its input; an input can name the result of an earlier step ("#E1"). The plan is yielded as a thought of the agent.
  • work: the agent runs the steps in order, each step's references replaced by the results they name, and yields each request and its result. A failed step stops the work.
  • solve: one model call writes the reply from the session, the plan and what each step found. It is streamed, and ends the turn.

So a turn is two model calls, however many steps the plan has, and the model reads the conversation twice instead of once per step. It suits tasks whose steps are known up front, such as a lookup and then an email built from it. Its trade-off is that the plan never sees a result: when a step returns something unexpected, the plan does not change; ReAct, which decides each step after the last one's result, adapts where ReWOO cannot.

func NewReWOOStrategy

func NewReWOOStrategy(llm LLM) ReWOOCognitiveStrategy

NewReWOOStrategy returns the ReWOO strategy of the model.

func (ReWOOCognitiveStrategy) Invoke

Invoke takes one ReWOO turn: the model plans, the agent works through the plan, and the model solves the task from what the plan found.

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session is a trace of the agent's experience, like the conversation of a chat completions API: the app keeps it and passes it in, and an agent has as many sessions as it has conversations. It is immutable: WithEvents returns a new one, and Events a copy, so sessions derived from the same one never share their events.

func NewSession

func NewSession(events ...Event) Session

NewSession returns a session of a new ID, with the events.

func NewSessionWithID

func NewSessionWithID(id string, events ...Event) Session

NewSessionWithID returns the session id, with the events.

func (Session) Events

func (s Session) Events() []Event

Events are the events of the session, oldest first: a copy.

func (Session) ID

func (s Session) ID() string

ID is the ID of the session.

func (Session) LastEvent

func (s Session) LastEvent() Event

LastEvent is the last event of the session, the zero Event when it has none.

func (Session) WithEvents

func (s Session) WithEvents(events ...Event) Session

WithEvents returns a new session, of the events of this one then the events, each chained to the one before it (an event that has a ParentID keeps it). This session is left as it was: the new one has its own copy of the events.

type SessionStream

type SessionStream struct {
	// contains filtered or unexported fields
}

SessionStream is a call of an agent (Invoke, Loop or Watch): its session, which each update sent grows, and the updates, read with Updates or Collect. The session given to the call only seeds it.

func (*SessionStream) Collect

func (s *SessionStream) Collect() (Session, error)

Collect reads the updates to their end, for the callers that want only the result: the session the call ended with, and its first error. The events the call added are those after the session it was given.

func (*SessionStream) Session

func (s *SessionStream) Session() Session

Session is the session so far: the one the call was given, with the events of every update sent. It may be ahead of the updates read; once they are read to their end, it is the session the call ended with.

func (*SessionStream) StopReason

func (s *SessionStream) StopReason() StopReason

StopReason is the last StopReason sent, "" since an error: once the updates are read to their end, how the call ended (StopReasonEndTurn, StopReasonMaxTurns, or "" for an error or a context that ended).

func (*SessionStream) Updates

func (s *SessionStream) Updates() iter.Seq[StreamUpdate]

Updates reads the updates as they come. An update that carries an Err is the error that ended the call, last, or, for a Watch, one of the loop on an event, after which the next event still comes. Stopping early leaves the call running until its context ends.

type SimpleAction

type SimpleAction struct {
	ActionDescriptor
	RunFn func(ctx context.Context, s Session, params map[string]any) (ActionExecutionResult, error)
}

SimpleAction is an action of a SimpleActionExecutor: its descriptor, and the function that runs it.

type SimpleActionExecutor

type SimpleActionExecutor struct {
	Actions map[string]SimpleAction
}

SimpleActionExecutor is an ActionExecutor of functions, by action ID.

func NewSimpleActionExecutor

func NewSimpleActionExecutor(actions ...SimpleAction) SimpleActionExecutor

NewSimpleActionExecutor returns the executor of the actions, by their ID.

func (SimpleActionExecutor) Descriptors

Descriptors describes the actions, ordered by ID so that what a model is told of them does not change from one turn to the next, allowing prompt caching for models that support it.

func (SimpleActionExecutor) Execute

Execute runs the actions one after the other. An unknown action fails: its result says so, for the model to see. The error of a function is an error.

type StopReason

type StopReason string

StopReason is why the agent stopped, as a model's stop reason.

const (
	// StopReasonEndTurn is an agent done: it replied, or has nothing to add.
	// Loop
	// stops. in other words, it is a natural end, or a stop sequence.
	StopReasonEndTurn StopReason = "end_turn"

	// StopReasonMaxTurns is a Loop that took all its turns without one ending
	// with
	// StopReasonEndTurn. It is not an error: the agent stopped where it was.
	StopReasonMaxTurns StopReason = "max_turns"

	// StopReasonLength is an agent whose answer was cut at the limit of tokens.
	// Loop
	// stops.
	StopReasonLength StopReason = "length"

	// StopReasonContentFilter is an agent whose model declined to answer. Loop
	// stops.
	StopReasonContentFilter StopReason = "content_filter"
)

type StrategyCandidate

type StrategyCandidate struct {
	Name        string
	Description string
	Strategy    CognitiveStrategy
}

StrategyCandidate is a strategy an AdaptiveCognitiveStrategy can choose: its name, what it suits (which the selector chooses by), and the strategy.

type StrategyFunc

type StrategyFunc func(ctx context.Context, inv Invocation) iter.Seq[StreamUpdate]

StrategyFunc is a function as a CognitiveStrategy.

func (StrategyFunc) Invoke

Invoke calls f.

type StrategySelector

type StrategySelector interface {
	Select(ctx context.Context, inv Invocation, candidates []StrategyCandidate) (string, error)
}

StrategySelector chooses the strategy that suits the task the session's last outside event asks for, among the candidates: its name, or "" when none clearly does.

type StreamChunk

type StreamChunk struct {
	// EventID is the event the chunk is a piece of.
	EventID EventID
	Data    []byte
	// Thinking tells that the chunk is a piece of the model's thinking as it
	// writes it, before the event, rather than of the event's text: it is only
	// to be shown, the thinking is kept whole with the event.
	Thinking bool
}

StreamChunk is a piece of the text of an event still being produced, as the model writes it.

type StreamUpdate

type StreamUpdate struct {
	Events []Event
	Chunk  *StreamChunk
	Err    error
	// StopReason is set only when the agent stops, on the last update: by the
	// strategy when the agent is done, by Loop when it took its turns. A turn
	// without one goes on: Loop takes another.
	StopReason StopReason
}

StreamUpdate is what a step adds: whole events, which enter the session, or a chunk of an event still being produced, which does not; or the error of the turn (Err). When the agent stops, the last update says why (StopReason).

type System1ChoiceAnswer

type System1ChoiceAnswer struct {
	// Choice is the most probable option.
	Choice string `json:"choice"`
	// Probabilities are those of the options, summing to 1.
	Probabilities map[string]float64 `json:"probabilities,omitempty"`
	// Confidence is how sure the model is of the choice, from 0 to 1.
	Confidence float64 `json:"confidence"`
}

System1ChoiceAnswer is the answer to a System1Question.

type System1Model

type System1Model interface {
	// AnswerChoice picks the option of the question that best fits the state.
	AnswerChoice(ctx context.Context, state string, q System1Question) (System1ChoiceAnswer, error)
	// AnswerScore rates the state on the question's rubric.
	AnswerScore(ctx context.Context, state string, q System1Question) (System1ScoreAnswer, error)
	// AnswerNoul tells how likely the question's statement is true of the
	// state.
	AnswerNoul(ctx context.Context, state string, q System1Question) (System1NoulAnswer, error)
}

System1Model is a System One model, as Jev (TypeSafe) defines one: given a state and a question about it, it answers in one pass, with calibrated probabilities. It generates no text: it decides among options defined in advance (a choice), rates on a rubric (a score), or tells how likely a statement is (a noul), so it cannot extract free-form values. The state is what the question is about: a short, dense text, or JSON (the conversation, the program's state). Ask several questions about the same state concurrently; pair a choice with a noul ("does any option apply?") rather than add a "none" option, and gate on the confidence as well as on the choice.

type System1NoulAnswer

type System1NoulAnswer struct {
	// Noul is the probability, from 0 to 1, that the statement is true.
	Noul float64 `json:"noul"`
}

System1NoulAnswer is the answer to a NoulQuestion.

type System1Question

type System1Question struct {
	Instructions string `json:"instructions"`
	// Criteria are the options, by name, and what each means (up to 255).
	Criteria map[string]string `json:"criteria,omitempty"`
}

System1Question asks to pick one option of Criteria.

type System1ScoreAnswer

type System1ScoreAnswer struct {
	// Score is the rating, normalized from 0 (the lowest level of the rubric)
	// to 1 (its highest).
	Score float64 `json:"score"`
	// Probabilities are those of the levels of the rubric, by name, summing to
	// 1.
	Probabilities map[string]float64 `json:"probabilities,omitempty"`
	// Confidence is how sure the model is of the score, from 0 to 1.
	Confidence float64 `json:"confidence"`
}

System1ScoreAnswer is the answer to a ScoreQuestion.

type System1StrategySelector

type System1StrategySelector struct {
	System1 System1Model
	// SelectionThreshold defaults DefaultSystem1SelectionThreshold when nil; a
	// pointer to 0 keeps whatever System1 chooses.
	SelectionThreshold *float64
	// ChoiceInstructions defaults DefaultSystem1StrategyChoiceInstructions.
	ChoiceInstructions string
}

System1StrategySelector is a StrategySelector of a System1Model: a choice among the candidates, by their descriptions, which it keeps when System1 is confident enough.

func (System1StrategySelector) Select

func (s System1StrategySelector) Select(
	ctx context.Context,
	inv Invocation,
	candidates []StrategyCandidate,
) (string, error)

Select asks System1 its choice. Under the threshold, it chooses none.

Directories

Path Synopsis
Package adapters adapts models to proxias: LLMSystem1, an LLM answering as a System1Model; the vendors' LLMs are in its subpackages (anthropic, openai).
Package adapters adapts models to proxias: LLMSystem1, an LLM answering as a System1Model; the vendors' LLMs are in its subpackages (anthropic, openai).
anthropic
Package anthropic is Claude for proxias, through the official SDK: an proxias.LLM (NewLLM), and a counter of what the calls cost (UsageCounter).
Package anthropic is Claude for proxias, through the official SDK: an proxias.LLM (NewLLM), and a counter of what the calls cost (UsageCounter).
openai
Package openai is an OpenAI model for proxias, through the official SDK and its Chat Completions API: an proxias.LLM (NewLLM).
Package openai is an OpenAI model for proxias, through the official SDK and its Chat Completions API: an proxias.LLM (NewLLM).
examples
agent-chat command
Command agent-chat is an assistant with one action, chatted with in one session, or served over HTTP (-serve) with one of the transports (-transport).
Command agent-chat is an assistant with one action, chatted with in one session, or served over HTTP (-serve) with one of the transports (-transport).
agent-cli command
Command agent-cli is a chat with an agent in the terminal: each line you type is a message to it, and it answers, using its actions when it needs to.
Command agent-cli is a chat with an agent in the terminal: each line you type is a message to it, and it answers, using its actions when it needs to.
agent-team command
Command agent-team has agents work together, orchestrated by the app: a manager delegates to a researcher (asking it is one of the manager's actions, agentdemo.Ask), then two agents talk in turn.
Command agent-team has agents work together, orchestrated by the app: a manager delegates to a researcher (asking it is one of the manager's actions, agentdemo.Ask), then two agents talk in turn.
agent-unattended command
Command agent-unattended runs an agent with nobody talking to it: it watches a probe of a system, and decides on its own whether to act.
Command agent-unattended runs an agent with nobody talking to it: it watches a probe of a system, and decides on its own whether to act.
agentbench command
Command agentbench compares the strategies on the scenarios of the agent examples: it runs each scenario on each strategy, and tells, per scenario and strategy, how often the task succeeded, the mean and spread of the calls to Claude, their tokens and cost, and the time a run took: in all, to its first action request or reply, per call to Claude, per turn of the scenario's agents, in the adaptive strategies' choices and in the agents' executions (summed over a run; a delegated agent's count in the run, inside the execution of the agent that asked it).
Command agentbench compares the strategies on the scenarios of the agent examples: it runs each scenario on each strategy, and tells, per scenario and strategy, how often the task succeeded, the mean and spread of the calls to Claude, their tokens and cost, and the time a run took: in all, to its first action request or reply, per call to Claude, per turn of the scenario's agents, in the adaptive strategies' choices and in the agents' executions (summed over a run; a delegated agent's count in the run, inside the execution of the agent that asked it).
agentdemo
Package agentdemo is what the agent examples share: the shell they run on (-shell, -claude), and how they print events.
Package agentdemo is what the agent examples share: the shell they run on (-shell, -claude), and how they print events.
Package schema builds the JSON Schema of the parameters of an action (an ActionDescriptor's InputSchema), one property per call:
Package schema builds the JSON Schema of the parameters of an action (an ActionDescriptor's InputSchema), one property per call:
transports
agenthttp
Package agenthttp serves an agent over HTTP: one transport among any (a WebSocket, gRPC, a queue would be others), which turns its requests into events for the agent and the agent's stream into its responses.
Package agenthttp serves an agent over HTTP: one transport among any (a WebSocket, gRPC, a queue would be others), which turns its requests into events for the agent and the agent's stream into its responses.
agentprotocolhttp
Package agentprotocolhttp serves an agent through the Agent Protocol (agentprotocol.ai, v1): a task is a session, a step is one turn of the agent on it.
Package agentprotocolhttp serves an agent through the Agent Protocol (agentprotocol.ai, v1): a task is a session, a step is one turn of the agent on it.
openaihttp
Package openaihttp serves agents through the OpenAI Chat Completions API, so that any OpenAI client talks to them as to models: an agent's ID is a model.
Package openaihttp serves agents through the OpenAI Chat Completions API, so that any OpenAI client talks to them as to models: an agent's ID is a model.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL