Documentation
¶
Overview ¶
Package agent provides a Go SDK for writing agents that run on agent-orca.
The SDK talks to the run's model-router (OPENAI_BASE_URL). The router keeps the conversation, injects the Agent's system prompt, and runs the Agent's tools and the built-in lifecycle tools (_done, _fail, _clarify, _handoff, _spawn, ...). Tools registered with Agent.Tool run in the agent process instead, e.g. a shell inside the agent's sandbox; they need spec.runtime.localTools on the Agent (docs/agent-run-tools.md).
Example::
a := agent.New()
a.Tool("search", "Search the web", params, func(args map[string]any) (string, error) {
return "results", nil
})
result, err := a.Run(context.Background(), "Find the latest news about LLMs")
if err != nil {
log.Fatal(err)
}
fmt.Println(result.Phase, result.Output)
Index ¶
- Constants
- Variables
- func Input() string
- type Agent
- type Option
- func WithAPIKey(key string) Option
- func WithBaseURL(url string) Option
- func WithHTTPClient(c *http.Client) Option
- func WithMaxTokens(n int) Option
- func WithModel(model string) Option
- func WithSystemPrompt(prompt string) Option
- func WithTemperature(t float64) Option
- func WithToolObserver(fn func(ToolEvent)) Option
- type RunOption
- type RunResult
- type ToolEvent
- type ToolHandler
- type ToolSpec
Constants ¶
const ( PhaseSucceeded = "Succeeded" PhaseFailed = "Failed" PhaseHandedOff = "HandedOff" PhaseWaitingForInput = "WaitingForInput" )
Run phases, matching the AgentRun phases they lead to.
Variables ¶
var ErrMaxTurns = errors.New("max turns exceeded")
ErrMaxTurns is returned in RunResult.FailureReason when the turn limit is hit.
Functions ¶
func Input ¶ added in v0.9.0
func Input() string
Input returns the run's input (AGENTORC_INPUT). In a sandbox, a multi-line input arrives base64-encoded in AGENTORC_INPUT_B64, because the sandbox gateway accepts no line breaks in environment values, while AGENTORC_INPUT holds a one-line version; Input prefers the exact one.
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent is the Go SDK for writing agents that run on agent-orca.
func (*Agent) Run ¶
Run executes the agent on the given input until the model ends the turn with text (see WithContinuePrompt) or the router closes the run.
type Option ¶
type Option func(*Agent)
Option configures an Agent.
func WithAPIKey ¶
WithAPIKey sets the bearer token for the router (default $OPENAI_API_KEY).
func WithBaseURL ¶
WithBaseURL overrides the model-router endpoint URL (default $OPENAI_BASE_URL, else http://localhost:8080/v1).
func WithHTTPClient ¶
WithHTTPClient sets a custom HTTP client. A turn streams for as long as the router's tool loop runs, so avoid a client-wide Timeout; use the context.
func WithMaxTokens ¶
WithMaxTokens sets the maximum tokens to generate per turn.
func WithModel ¶
WithModel sets the model identifier sent with each request. The router chooses the provider, so this is usually left unset.
func WithSystemPrompt ¶
WithSystemPrompt sets a system instruction sent with the first request, in addition to the Agent's spec.systemPrompt, which the router injects.
func WithTemperature ¶
WithTemperature sets the sampling temperature.
func WithToolObserver ¶ added in v0.9.0
WithToolObserver calls fn after each tool call the agent runs, e.g. to log progress.
type RunOption ¶
type RunOption func(*runConfig)
RunOption configures a Run call.
func WithContinuePrompt ¶ added in v0.9.0
WithContinuePrompt keeps the run going when the model replies with text instead of a tool call: prompt is sent as the next user message. The run then ends only when the model calls a lifecycle tool (_done, _fail, ...), which the router reports by closing the run. Without it, a text reply ends the run.
func WithMaxTurns ¶
WithMaxTurns sets the maximum number of requests to the router (default 200).
type RunResult ¶
type RunResult struct {
// Output is the model's last text reply.
Output string
// Phase is one of the Phase* constants.
Phase string
// FailureReason explains a Failed phase.
FailureReason string
}
RunResult is the final result of an agent run.
type ToolHandler ¶
ToolHandler is the function signature for a custom tool handler. It receives the parsed arguments as a map and returns a string result.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package devtools gives a coding agent a shell and file tools over one workspace directory: shell, read_file, write_file, edit_file, list_dir and grep.
|
Package devtools gives a coding agent a shell and file tools over one workspace directory: shell, read_file, write_file, edit_file, list_dir and grep. |