phaseoagent

README

Phaseo Agent SDK (Go)

agent-sdk-go is the native Go runtime for building tool-using applications on Phaseo Gateway.

It provides:

• CreateAgent(...)
• DefineTool(...)
• CreateGatewayAgentClient(...)
• concurrent local tools, contexts, timeouts, and model retry/backoff
• human-review pauses and Agent.Continue(...)
• lifecycle events, serializable run state, and Phaseo Devtools capture

Install

go get github.com/phaseoteam/Phaseo/packages/sdk/agent-sdk-go@latest

Documentation

Index

• type Agent
  • func CreateAgent(definition AgentDefinition) *Agent
  • func (a *Agent) Continue(ctx context.Context, options ContinueOptions) (result RunResult, err error)
  • func (a *Agent) ContinueStream(ctx context.Context, options ContinueOptions) *StreamResult
  • func (a *Agent) Run(ctx context.Context, options RunOptions) (result RunResult, err error)
  • func (a *Agent) Stream(ctx context.Context, options RunOptions) *StreamResult
• type AgentDefinition
• type AgentEvent
• type ApprovalPredicate
• type ContinueOptions
• type DevtoolsConfig
  • func CreateAgentDevtools(directory string) *DevtoolsConfig
• type EventHandler
• type GatewayAgentClient
  • func CreateGatewayAgentClient(options GatewayAgentClientOptions) (*GatewayAgentClient, error)
  • func (g *GatewayAgentClient) Generate(ctx context.Context, request ModelRequest) (ModelResponse, error)
  • func (g *GatewayAgentClient) Stream(ctx context.Context, request ModelRequest) <-chan ModelStreamEvent
• type GatewayAgentClientOptions
• type HumanPause
• type HumanReviewContext
• type HumanReviewRequest
• type Message
• type ModelClient
• type ModelRequest
• type ModelResponse
• type ModelRetryConfig
• type ModelStreamEvent
• type NextTurnParams
• type PendingToolCall
• type RunOptions
• type RunRecord
• type RunResult
• type RunStep
• type RuntimeContext
• type StateAccessor
• type StopCondition
  • func FinishReasonIs(reason string) StopCondition
  • func HasToolCall(name string) StopCondition
  • func MaxCost(limit float64) StopCondition
  • func MaxDuration(limit time.Duration) StopCondition
  • func MaxTokensUsed(limit int) StopCondition
  • func StepCountIs(limit int) StopCondition
• type StopState
• type StreamResult
  • func (s *StreamResult) Cancel()
  • func (s *StreamResult) Events() <-chan AgentEvent
  • func (s *StreamResult) Result() (RunResult, error)
  • func (s *StreamResult) Text() <-chan string
• type StreamingModelClient
• type Tool
  • func DefineTool(tool Tool) Tool
• type ToolCall
• type ToolDecision
• type ToolExecutionConfig
• type ToolOutput
• type TurnContext
• type UsageSummary
• type Validator

Types

type Agent

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

func CreateAgent

func CreateAgent(definition AgentDefinition) *Agent

func (*Agent) Continue

func (a *Agent) Continue(ctx context.Context, options ContinueOptions) (result RunResult, err error)

func (*Agent) ContinueStream

func (a *Agent) ContinueStream(ctx context.Context, options ContinueOptions) *StreamResult

func (*Agent) Run

func (a *Agent) Run(ctx context.Context, options RunOptions) (result RunResult, err error)

func (*Agent) Stream

func (a *Agent) Stream(ctx context.Context, options RunOptions) *StreamResult

type AgentDefinition

type AgentDefinition struct {
	ID                  string
	Model               string
	Preset              string
	Instructions        string
	Tools               []Tool
	MaxSteps            int
	ParseOutput         func(string) (any, error)
	HumanReview         func(HumanReviewContext) *HumanReviewRequest
	ModelRetry          ModelRetryConfig
	ToolExecution       ToolExecutionConfig
	StopWhen            []StopCondition
	RequireApproval     func(ToolCall, RuntimeContext) (bool, error)
	OutputSchema        Validator
	DynamicModel        func(TurnContext) string
	DynamicInstructions func(TurnContext) string
	Temperature         func(TurnContext) *float64
	MaxOutputTokens     func(TurnContext) *int
	TopP                func(TurnContext) *float64
	DynamicTools        func(TurnContext) []Tool
}

type AgentEvent

type AgentEvent struct {
	Type      string         `json:"type"`
	RunID     string         `json:"run_id"`
	AgentID   string         `json:"agent_id"`
	Timestamp string         `json:"timestamp"`
	Status    string         `json:"status"`
	Details   map[string]any `json:"details,omitempty"`
}

type ApprovalPredicate

type ApprovalPredicate func(any, RuntimeContext) (bool, error)

type ContinueOptions

type ContinueOptions struct {
	Run           RunResult
	RunID         string
	Client        ModelClient
	Context       any
	Model         string
	Preset        string
	MaxSteps      int
	HumanInput    string
	ModelRetry    *ModelRetryConfig
	ToolExecution *ToolExecutionConfig
	OnEvent       EventHandler
	Devtools      *DevtoolsConfig
	Approvals     []ToolDecision
	Rejections    []ToolDecision
	ToolOutputs   []ToolOutput
	State         StateAccessor
}

type DevtoolsConfig

type DevtoolsConfig struct {
	Enabled   bool
	Directory string
}

func CreateAgentDevtools

func CreateAgentDevtools(directory string) *DevtoolsConfig

type EventHandler

type EventHandler func(AgentEvent)

type GatewayAgentClient

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

func CreateGatewayAgentClient

func CreateGatewayAgentClient(options GatewayAgentClientOptions) (*GatewayAgentClient, error)

func (*GatewayAgentClient) Generate

func (g *GatewayAgentClient) Generate(ctx context.Context, request ModelRequest) (ModelResponse, error)

func (*GatewayAgentClient) Stream

func (g *GatewayAgentClient) Stream(ctx context.Context, request ModelRequest) <-chan ModelStreamEvent

type GatewayAgentClientOptions

type GatewayAgentClientOptions struct {
	Client           *phaseo.Phaseo
	HTTPClient       *http.Client
	Headers          map[string]string
	APIKey           string
	BaseURL          string
	Model            string
	Preset           string
	Provider         map[string]any
	Reasoning        map[string]any
	Temperature      *float64
	MaxOutputTokens  *int
	ParallelToolCall *bool
	Metadata         map[string]string
	User             string
	IncludeMeta      *bool
	GatewayTools     []map[string]any
	ToolChoice       any
	ProviderOptions  map[string]any
	PromptCacheKey   string
	ConfigureRequest func(*gen.ResponsesRequest)
}

type HumanPause

type HumanPause struct {
	Reason           string
	Payload          any
	RequestedAt      string
	Kind             string
	PendingToolCalls []PendingToolCall
}

type HumanReviewContext

type HumanReviewContext struct {
	RunID        string
	AgentID      string
	StepIndex    int
	Input        any
	Context      any
	Messages     []Message
	Response     ModelResponse
	ParsedOutput any
}

type HumanReviewRequest

type HumanReviewRequest struct {
	Reason  string
	Payload any
}

type Message

type Message struct {
	Role       string
	Content    string
	ToolCalls  []ToolCall
	ToolCallID string
	Name       string
	IsError    bool
}

type ModelClient

type ModelClient interface {
	Generate(ctx context.Context, request ModelRequest) (ModelResponse, error)
}

type ModelRequest

type ModelRequest struct {
	AgentID         string
	Model           string
	Instructions    string
	Messages        []Message
	Tools           []Tool
	Context         any
	Temperature     *float64
	MaxOutputTokens *int
	TopP            *float64
	Stream          bool
}

type ModelResponse

type ModelResponse struct {
	Message          Message
	Usage            map[string]any
	RequestID        string
	NativeResponseID string
	Provider         string
	Model            string
	ResponseMeta     map[string]any
	FinishReason     string
	Cost             float64
	Warnings         []map[string]string
}

type ModelRetryConfig

type ModelRetryConfig struct {
	MaxRetries int
	Backoff    time.Duration
}

type ModelStreamEvent

type ModelStreamEvent struct {
	Type, Delta string
	Item        any
	Response    *ModelResponse
	Err         error
}

type NextTurnParams

type NextTurnParams struct {
	Model, Instructions string
	Temperature, TopP   *float64
	MaxOutputTokens     *int
	Tools               []Tool
}

type PendingToolCall

type PendingToolCall struct {
	Call         ToolCall
	Kind, Reason string
}

type RunOptions

type RunOptions struct {
	Input         any
	Client        ModelClient
	Context       any
	Model         string
	MaxSteps      int
	Preset        string
	ModelRetry    *ModelRetryConfig
	ToolExecution *ToolExecutionConfig
	OnEvent       EventHandler
	Devtools      *DevtoolsConfig
	State         StateAccessor
}

type RunRecord

type RunRecord struct {
	ID         string
	AgentID    string
	Status     string
	Input      any
	Messages   []Message
	StepCount  int
	Result     any
	Error      string
	Context    any
	Pause      *HumanPause
	CreatedAt  string
	UpdatedAt  string
	StopReason string
	Usage      UsageSummary
	NextTurn   *NextTurnParams
}

type RunResult

type RunResult struct {
	Run      RunRecord
	Steps    []RunStep
	Output   any
	Messages []Message
	Usage    UsageSummary
}

type RunStep

type RunStep struct {
	Index            int
	Status           string
	ToolCalls        []ToolCall
	RequestID        string
	NativeResponseID string
	Provider         string
	Model            string
	ModelAttempts    int
	Usage            map[string]any
	ResponseMeta     map[string]any
	Error            string
	FinishReason     string
	Warnings         []map[string]string
}

type RuntimeContext

type RuntimeContext struct {
	RunID        string
	AgentID      string
	StepIndex    int
	Context      any
	ToolCall     ToolCall
	EmitProgress func(any) error
	SetContext   func(any)
}

type StateAccessor

type StateAccessor interface {
	Load(context.Context, string) (*RunResult, error)
	Save(context.Context, RunResult) error
}

type StopCondition

type StopCondition func(StopState) (string, bool)

func FinishReasonIs

func FinishReasonIs(reason string) StopCondition

func HasToolCall

func HasToolCall(name string) StopCondition

func MaxCost

func MaxCost(limit float64) StopCondition

func MaxDuration

func MaxDuration(limit time.Duration) StopCondition

func MaxTokensUsed

func MaxTokensUsed(limit int) StopCondition

func StepCountIs

func StepCountIs(limit int) StopCondition

type StopState

type StopState struct {
	StepCount    int
	Usage        UsageSummary
	ToolCalls    []ToolCall
	FinishReason string
	Elapsed      time.Duration
}

type StreamResult

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

func (*StreamResult) Cancel

func (s *StreamResult) Cancel()

func (*StreamResult) Events

func (s *StreamResult) Events() <-chan AgentEvent

func (*StreamResult) Result

func (s *StreamResult) Result() (RunResult, error)

func (*StreamResult) Text

func (s *StreamResult) Text() <-chan string

type StreamingModelClient

type StreamingModelClient interface {
	ModelClient
	Stream(context.Context, ModelRequest) <-chan ModelStreamEvent
}

type Tool

type Tool struct {
	ID                 string
	Description        string
	Parameters         map[string]any
	Execute            func(input any, ctx RuntimeContext) (any, error)
	Timeout            time.Duration
	InputSchema        Validator
	OutputSchema       Validator
	EventSchema        Validator
	RequireApproval    bool
	Approval           ApprovalPredicate
	OnToolCalled       func(any, RuntimeContext) (any, bool, error)
	OnResponseReceived func(any, RuntimeContext) (any, error)
	NextTurn           *NextTurnParams
	OnError            string
}

func DefineTool

func DefineTool(tool Tool) Tool

type ToolCall

type ToolCall struct {
	ID    string
	Name  string
	Input any
}

type ToolDecision

type ToolDecision struct{ ToolCallID, Reason string }

type ToolExecutionConfig

type ToolExecutionConfig struct{ Concurrency int }

type ToolOutput

type ToolOutput struct {
	ToolCallID string
	Output     any
}

type TurnContext

type TurnContext struct {
	NumberOfTurns, StepIndex int
	Messages                 []Message
	Context                  any
	LastToolCall             *ToolCall
}

type UsageSummary

type UsageSummary struct {
	InputTokens, OutputTokens, CachedTokens, TotalTokens int
	Cost                                                 float64
}

type Validator

type Validator func(any) (any, error)