Client.Invoke performs one request and returns a complete *inference.Response. The client resolves the model, encodes the request, drains the response, and returns normalized assistant content and terminal metadata.

API surface

type Client interface {
	Invoke(ctx context.Context, req Request) (*Response, error)
}

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

response, err := client.Invoke(ctx, inference.Request{
	Model: model.CustomModel(
		model.ProviderName("acme"), model.APIFormatOpenAI,
		"https://api.example.test", "chat-1",
	),
	Messages: content.AgenticMessages{
		&content.UserMessage{Message: content.Message{
			Role: content.RoleUser,
			Blocks: []content.Block{&content.TextBlock{Text: "Hello"}},
		}},
	},
})
if err != nil {
	// Inspect typed errors with errors.As where a retry or user message is needed.
	return err
}
if response.Message != nil {
	// Response.Message is the assistant turn, not a provider JSON envelope.
	_ = response.Message.Blocks
}

Request.Model is secret-free; authentication is supplied by the configured client. Request.System is per-call instruction text, while the message thread is preserved separately. A successful response may have nil Usage or an unknown zero FinishReason when the provider did not report metadata.

Error and cancellation ownership

The caller owns the context and decides whether an error is retryable. The client owns transport response bodies and closes them before returning. A cancelled context should stop work and return its cancellation error or a wrapped transport error; callers should not retry a request after the context is done.

Proof

Source: inference/client.go
Tests: inference/client_test.go, inference/transport/client_test.go
Example: inference/examples/invoke/main.go