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
- type ActionDescriptor
- type ActionExecutionRequest
- type ActionExecutionResult
- type ActionExecutor
- type AdaptiveCognitiveStrategy
- type Agent
- func (a *Agent) AsSource() EventSource
- func (a *Agent) Invoke(ctx context.Context, s Session, strategy CognitiveStrategy) (*SessionStream, error)
- func (a *Agent) Loop(ctx context.Context, s Session, strategy CognitiveStrategy) (*SessionStream, error)
- func (a *Agent) Watch(ctx context.Context, s Session, events <-chan Event, ...) (*SessionStream, error)
- type AgentBias
- type AgentMiddleware
- type AgentPersona
- type CognitiveStrategy
- type Event
- func NewActionExecutionRequestEvent(source EventSource, req ActionExecutionRequest) (Event, error)
- func NewActionExecutionResultEvent(source EventSource, res ActionExecutionResult) (Event, error)
- func NewEvent(t EventType, source EventSource, payload []byte) Event
- func NewEventsFromLLMMessage(currentAgentSource EventSource, m LLMMessage) []Event
- func NewMessageEvent(source EventSource, text string) Event
- func NewThoughtEvent(source EventSource, chunk LLMChunk) Event
- type EventID
- type EventSource
- type EventSourceType
- type EventType
- type Invocation
- type LLM
- type LLMChunk
- type LLMMessage
- type LLMMessageRole
- type LLMPart
- type LLMRequest
- type LLMStrategySelector
- type LLMToolCall
- type LLMToolResult
- type MarkdownMemory
- type MemoryProvider
- type ObservePlanExecuteCognitiveStrategy
- type Prompt
- func (p *Prompt) AddBulletPoint(text string) *Prompt
- func (p *Prompt) AddLabeledBulletPoint(label, text string) *Prompt
- func (p *Prompt) AddLine(line string) *Prompt
- func (p *Prompt) AddParagraph(text string) *Prompt
- func (p *Prompt) AddSection(title, content string) *Prompt
- func (p *Prompt) String() string
- type ReActCognitiveStrategy
- type ReWOOCognitiveStrategy
- type Session
- type SessionStream
- type SimpleAction
- type SimpleActionExecutor
- type StopReason
- type StrategyCandidate
- type StrategyFunc
- type StrategySelector
- type StreamChunk
- type StreamUpdate
- type System1ChoiceAnswer
- type System1Model
- type System1NoulAnswer
- type System1Question
- type System1ScoreAnswer
- type System1StrategySelector
Constants ¶
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.
const DefaultMaxTurns = 8
DefaultMaxTurns default value for the maximum number of turns Agent.Loop can perform.
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.
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.
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.
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.
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.
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.
const DefaultSystem1SelectionThreshold = 0.5
DefaultSystem1SelectionThreshold is the confidence under which a System1StrategySelector chooses no strategy, when its SelectionThreshold is nil.
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 ¶
func (s AdaptiveCognitiveStrategy) Invoke(ctx context.Context, inv Invocation) iter.Seq[StreamUpdate]
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 ¶
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.
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 NewSystemSource ¶
func NewSystemSource(id string) EventSource
NewSystemSource is the system 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 ¶
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 ¶
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 ¶
LLMToolCall is a model's call of a tool: an action request.
type LLMToolResult ¶
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 ¶
func (m MarkdownMemory) Recall(context.Context, Invocation) (string, error)
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 ¶
func (s ObservePlanExecuteCognitiveStrategy) Invoke(ctx context.Context, inv Invocation) iter.Seq[StreamUpdate]
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 (*Prompt) AddBulletPoint ¶
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 ¶
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 ¶
AddLine adds a line, right under the block before it unless that is a paragraph. A blank line is ignored.
func (*Prompt) AddParagraph ¶
AddParagraph adds text as is. A blank text is ignored.
func (*Prompt) AddSection ¶
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.
type ReActCognitiveStrategy ¶
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 ¶
func (s ReActCognitiveStrategy) Invoke(ctx context.Context, inv Invocation) iter.Seq[StreamUpdate]
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 ¶
func (s ReWOOCognitiveStrategy) Invoke(ctx context.Context, inv Invocation) iter.Seq[StreamUpdate]
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 ¶
NewSession returns a session of a new ID, with the events.
func NewSessionWithID ¶
NewSessionWithID returns the session id, with the events.
func (Session) LastEvent ¶
LastEvent is the last event of the session, the zero Event when it has none.
func (Session) WithEvents ¶
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 ¶
func (e SimpleActionExecutor) Descriptors(context.Context, Session) ([]ActionDescriptor, error)
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 ¶
func (e SimpleActionExecutor) Execute( ctx context.Context, s Session, requests []ActionExecutionRequest, ) ([]ActionExecutionResult, error)
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 ¶
func (f StrategyFunc) Invoke(ctx context.Context, inv Invocation) iter.Seq[StreamUpdate]
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.
Source Files
¶
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. |