openresponses

package
v1.20260325.0 Latest Latest
Warning

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

 Go to latest Published: Mar 25, 2026 License: MIT Imports: 8 Imported by: 1

Documentation

Overview

Package openresponses implements an HTTP client for the OpenClaw OpenAI Responses API-compatible endpoint (POST /v1/responses).

Reference: https://docs.openclaw.ai/gateway/openresponses-http-api

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func InputFromItems 

func InputFromItems(items []InputItem) json.RawMessage

InputFromItems creates a Request.Input from an array of InputItem values.

func InputFromString 

func InputFromString(s string) json.RawMessage

InputFromString creates a Request.Input from a plain string.

Types

type APIError 

type APIError struct {
	Error struct {
		Message string `json:"message"`
		Type    string `json:"type"`
	} `json:"error"`
}

APIError is the error envelope returned by the gateway for non-200 responses.

type Client 

type Client struct {
	// BaseURL is the gateway base URL (e.g. "http://127.0.0.1:18789").
	BaseURL string

	// Token is the bearer token for authentication.
	Token string

	// AgentID is the optional OpenClaw agent id (sent via x-openclaw-agent-id).
	AgentID string

	// SessionKey is the optional session key (sent via x-openclaw-session-key).
	SessionKey string

	// HTTPClient is the underlying HTTP client. If nil, http.DefaultClient is used.
	HTTPClient *http.Client
}

Client calls the OpenClaw OpenAI Responses API-compatible endpoint.

func (*Client) Create 

func (c *Client) Create(ctx context.Context, req Request) (*Response, error)

Create sends a non-streaming response request.

func (*Client) CreateStream 

func (c *Client) CreateStream(ctx context.Context, req Request) (*Stream, error)

CreateStream sends a streaming response request and returns a Stream. The caller must call Stream.Close when done.

type ContentPart 

type ContentPart struct {
	Type string `json:"type"` // "input_text", "output_text", "input_image", "input_file"

	// text fields (input_text, output_text)
	Text string `json:"text,omitempty"`

	// image/file fields (input_image, input_file)
	Source *ContentSource `json:"source,omitempty"`
}

ContentPart is a part of a message's content array.

type ContentPartEvent 

type ContentPartEvent struct {
	Type         string     `json:"type"`
	ItemID       string     `json:"item_id"`
	OutputIndex  int        `json:"output_index"`
	ContentIndex int        `json:"content_index"`
	Part         OutputText `json:"part"`
}

ContentPartEvent carries a content part with indices. Used by: response.content_part.added, response.content_part.done.

type ContentSource 

type ContentSource struct {
	Type      string `json:"type"`                 // "url" or "base64"
	URL       string `json:"url,omitempty"`        // for type "url"
	MediaType string `json:"media_type,omitempty"` // for type "base64"
	Data      string `json:"data,omitempty"`       // for type "base64"
	Filename  string `json:"filename,omitempty"`   // optional, for input_file base64
}

ContentSource describes the source of an image or file.

type ErrorInfo 

type ErrorInfo struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

ErrorInfo describes an error in a failed response.

type FunctionTool 

type FunctionTool struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,omitempty"`
}

FunctionTool is the function specification inside a ToolDefinition.

type HTTPError 

type HTTPError struct {
	// StatusCode is the HTTP response status code.
	StatusCode int
	// Body is the response body truncated to 4096 bytes.
	Body string
	// RetryAfter is the value of the Retry-After header, if present.
	RetryAfter string
}

HTTPError represents a non-200 response from the gateway.

func (*HTTPError) Error 

func (e *HTTPError) Error() string

type InputItem 

type InputItem struct {
	Type string `json:"type"` // "message", "function_call", "function_call_output", "reasoning", "item_reference"

	// message fields
	Role    string          `json:"role,omitempty"`    // "system", "developer", "user", "assistant"
	Content json.RawMessage `json:"content,omitempty"` // string or []ContentPart

	// function_call fields
	ID        string `json:"id,omitempty"`
	CallID    string `json:"call_id,omitempty"`
	Name      string `json:"name,omitempty"`
	Arguments string `json:"arguments,omitempty"`

	// function_call_output fields
	Output string `json:"output,omitempty"`

	// reasoning fields
	EncryptedContent string `json:"encrypted_content,omitempty"`
	Summary          string `json:"summary,omitempty"`
}

InputItem is a single input item. Set Type to select the variant. Only fields relevant to the chosen type should be populated.

func FunctionCallItem 

func FunctionCallItem(callID, name, arguments string) InputItem

FunctionCallItem creates a function_call InputItem.

func FunctionCallOutputItem 

func FunctionCallOutputItem(callID, output string) InputItem

FunctionCallOutputItem creates a function_call_output InputItem.

func MessageItem 

func MessageItem(role, content string) InputItem

MessageItem creates a message InputItem with string content.

func MessageItemParts 

func MessageItemParts(role string, parts []ContentPart) InputItem

MessageItemParts creates a message InputItem with structured content parts.

type OutputItem 

type OutputItem struct {
	Type string `json:"type"` // "message", "function_call", "reasoning"

	// Common
	ID     string `json:"id"`
	Status string `json:"status,omitempty"` // "in_progress", "completed"

	// message fields
	Role    string       `json:"role,omitempty"`
	Content []OutputText `json:"content,omitempty"`

	// function_call fields
	CallID    string `json:"call_id,omitempty"`
	Name      string `json:"name,omitempty"`
	Arguments string `json:"arguments,omitempty"`

	// reasoning fields (not currently emitted)
	Summary string `json:"summary,omitempty"`
}

OutputItem is a single item in the response output array. Discriminated on Type.

type OutputItemEvent 

type OutputItemEvent struct {
	Type        string     `json:"type"`
	OutputIndex int        `json:"output_index"`
	Item        OutputItem `json:"item"`
}

OutputItemEvent carries an output item with its index. Used by: response.output_item.added, response.output_item.done.

type OutputText 

type OutputText struct {
	Type string `json:"type"` // "output_text"
	Text string `json:"text"`
}

OutputText is a text content part in an output message.

type OutputTextDeltaEvent 

type OutputTextDeltaEvent struct {
	Type         string `json:"type"` // "response.output_text.delta"
	ItemID       string `json:"item_id"`
	OutputIndex  int    `json:"output_index"`
	ContentIndex int    `json:"content_index"`
	Delta        string `json:"delta"`
}

OutputTextDeltaEvent carries a text delta chunk.

type OutputTextDoneEvent 

type OutputTextDoneEvent struct {
	Type         string `json:"type"` // "response.output_text.done"
	ItemID       string `json:"item_id"`
	OutputIndex  int    `json:"output_index"`
	ContentIndex int    `json:"content_index"`
	Text         string `json:"text"`
}

OutputTextDoneEvent carries the completed text.

type Reasoning 

type Reasoning struct {
	Effort  string `json:"effort,omitempty"`  // "low", "medium", "high"
	Summary string `json:"summary,omitempty"` // "auto", "concise", "detailed"
}

Reasoning controls the model's reasoning behavior.

type Request 

type Request struct {
	// Model is required. Examples: "openclaw", "openclaw:main", "agent:beta".
	Model string `json:"model"`

	// Input is the conversation input — either a plain string or an array of
	// InputItem values. Use InputFromString or InputFromItems to construct.
	Input json.RawMessage `json:"input"`

	// Instructions is an optional system prompt merged into the conversation.
	Instructions string `json:"instructions,omitempty"`

	// Tools defines client tool (function) definitions.
	Tools []ToolDefinition `json:"tools,omitempty"`

	// ToolChoice controls tool selection: "auto", "none", "required", or
	// a specific function choice (use ToolChoiceFunction).
	ToolChoice any `json:"tool_choice,omitempty"`

	// Stream enables SSE streaming when true.
	Stream bool `json:"stream,omitempty"`

	// MaxOutputTokens is a best-effort output length limit.
	MaxOutputTokens *int `json:"max_output_tokens,omitempty"`

	// User is a stable session routing key.
	User string `json:"user,omitempty"`

	// Temperature is accepted but currently ignored by the gateway.
	Temperature *float64 `json:"temperature,omitempty"`

	// TopP is accepted but currently ignored by the gateway.
	TopP *float64 `json:"top_p,omitempty"`

	// MaxToolCalls is accepted but currently ignored.
	MaxToolCalls *int `json:"max_tool_calls,omitempty"`

	// Metadata is arbitrary key-value metadata.
	Metadata map[string]string `json:"metadata,omitempty"`

	// Store is accepted but currently ignored.
	Store *bool `json:"store,omitempty"`

	// PreviousResponseID links to a prior response for multi-turn.
	PreviousResponseID string `json:"previous_response_id,omitempty"`

	// Reasoning controls reasoning effort/summary.
	Reasoning *Reasoning `json:"reasoning,omitempty"`

	// Truncation is "auto" or "disabled".
	Truncation string `json:"truncation,omitempty"`
}

Request is the body for POST /v1/responses.

type Response 

type Response struct {
	ID        string       `json:"id"`         // "resp_<uuid>"
	Object    string       `json:"object"`     // "response"
	CreatedAt int64        `json:"created_at"` // Unix epoch seconds
	Status    string       `json:"status"`     // "in_progress", "completed", "failed", "cancelled", "incomplete"
	Model     string       `json:"model"`
	Output    []OutputItem `json:"output"`
	Usage     Usage        `json:"usage"`
	Error     *ErrorInfo   `json:"error,omitempty"`
}

Response is the response resource from POST /v1/responses.

type ResponseEvent 

type ResponseEvent struct {
	Type     string   `json:"type"`
	Response Response `json:"response"`
}

ResponseEvent carries a full Response resource. Used by: response.created, response.in_progress, response.completed, response.failed.

type Stream 

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

Stream represents an active SSE stream of response events.

func (*Stream) Close 

func (s *Stream) Close() error

Close closes the underlying HTTP response body.

func (*Stream) Recv 

func (s *Stream) Recv() (*StreamEvent, error)

Recv reads the next StreamEvent from the SSE stream. Returns io.EOF when the stream ends (data: [DONE]).

The caller can inspect StreamEvent.EventType to determine the event kind, then unmarshal StreamEvent.RawData into the appropriate typed event struct (ResponseEvent, OutputItemEvent, ContentPartEvent, OutputTextDeltaEvent, etc.).

type StreamEvent 

type StreamEvent struct {
	EventType string          `json:"-"`    // set from SSE event line
	Type      string          `json:"type"` // matches EventType
	RawData   json.RawMessage `json:"-"`    // full JSON data line
}

StreamEvent is a typed SSE event from a streaming response. The EventType field corresponds to the SSE "event:" line.

type ToolChoiceFunction 

type ToolChoiceFunction struct {
	Type     string                     `json:"type"` // "function"
	Function ToolChoiceFunctionSelector `json:"function"`
}

ToolChoiceFunction specifies a particular function for tool_choice.

type ToolChoiceFunctionSelector 

type ToolChoiceFunctionSelector struct {
	Name string `json:"name"`
}

ToolChoiceFunctionSelector names the function to call.

type ToolDefinition 

type ToolDefinition struct {
	Type     string       `json:"type"` // "function"
	Function FunctionTool `json:"function"`
}

ToolDefinition defines a client function tool.

type Usage 

type Usage struct {
	InputTokens  int `json:"input_tokens"`
	OutputTokens int `json:"output_tokens"`
	TotalTokens  int `json:"total_tokens"`
}

Usage reports token counts.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.