metaagent

ExampleNew demonstrates the retained compatibility constructor. Prefer NewRouted for explicit provider selection in new applications.

package main

import (
	"context"
	"fmt"

	"chainguard.dev/driftlessaf/agents/metaagent"
	"chainguard.dev/driftlessaf/agents/promptbuilder"
	"chainguard.dev/driftlessaf/agents/toolcall"
)

// request is an example request type that implements promptbuilder.Bindable.
type request struct {
	Query string
}

func (r *request) Bind(p *promptbuilder.Prompt) (*promptbuilder.Prompt, error) {
	return p.BindXML("query", struct {
		XMLName struct{} `xml:"query"`
		Content string   `xml:",chardata"`
	}{
		Content: r.Query,
	})
}

// response is an example structured response type.
type response struct {
	Answer string `json:"answer"`
}

func main() {
	ctx := context.Background()

	tools := toolcall.NewEmptyToolsProvider[*response]()
	config := metaagent.Config[*response, toolcall.EmptyTools]{
		Tools: tools,
	}

	// An unsupported model prefix returns an error.
	_, err := metaagent.New[*request](ctx, "my-project", "us-central1", "unknown-model", config)
	if err != nil {
		fmt.Println("error:", err)
	}
}

Output:
error: unsupported model: unknown-model (expected gemini-*, claude-*, or publisher/model format)

ExampleNewRouted demonstrates explicit provider selection with a test-only provider that reuses the OpenAI Chat Completions protocol.

package main

import (
	"context"
	"fmt"

	"chainguard.dev/driftlessaf/agents/executor/openai/chatcompletionexecutor"
	"chainguard.dev/driftlessaf/agents/metaagent"
	"chainguard.dev/driftlessaf/agents/modelrouter"
	"chainguard.dev/driftlessaf/agents/promptbuilder"
	"chainguard.dev/driftlessaf/agents/toolcall"
	"github.com/openai/openai-go/v3"
)

// request is an example request type that implements promptbuilder.Bindable.
type request struct {
	Query string
}

func (r *request) Bind(p *promptbuilder.Prompt) (*promptbuilder.Prompt, error) {
	return p.BindXML("query", struct {
		XMLName struct{} `xml:"query"`
		Content string   `xml:",chardata"`
	}{
		Content: r.Query,
	})
}

// response is an example structured response type.
type response struct {
	Answer string `json:"answer"`
}

func main() {
	const provider modelrouter.Provider = "example-provider"
	selection := modelrouter.Selection{Provider: provider, LogicalModel: "example/model"}
	routes, err := modelrouter.NewRegistry(modelrouter.Route{
		Selection:       selection,
		Protocol:        modelrouter.ProtocolOpenAIChatCompletions,
		ProviderModelID: "opaque-deployment-id",
		Attribution: modelrouter.Attribution{
			ProviderName: "example.provider",
			LegacySystem: "example.provider",
		},
		Capabilities: modelrouter.Capabilities{
			ToolCalling:        true,
			TerminalSubmission: true,
		},
	})
	if err != nil {
		panic(err)
	}
	adapters, err := metaagent.NewOpenAIChatCompletionsAdapterRegistry(
		metaagent.OpenAIChatCompletionsRegistration{
			Provider: provider,
			Adapter: func(_ context.Context, plan modelrouter.Plan) (metaagent.OpenAIChatCompletionsBinding, error) {
				// A real application prepares the SDK client with its provider-owned
				// endpoint and credential here, outside the route plan.
				return metaagent.NewOpenAIChatCompletionsBinding(
					plan, openai.Client{}, chatcompletionexecutor.TokenLimitMaxTokens, nil,
				)
			},
		},
	)
	if err != nil {
		panic(err)
	}
	router, err := metaagent.NewRouter(routes, metaagent.AdapterRegistries{OpenAIChatCompletions: adapters})
	if err != nil {
		panic(err)
	}
	prompt, err := promptbuilder.NewPrompt("answer the query")
	if err != nil {
		panic(err)
	}
	agent, err := metaagent.NewRouted[*request](context.Background(), router, selection, metaagent.Config[*response, toolcall.EmptyTools]{
		UserPrompt: prompt,
		Tools:      toolcall.NewEmptyToolsProvider[*response](),
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(agent != nil)
}

Output:
true

target := exampleRuntime().Target(metaagent.TargetConfig{
	Provider: modelrouter.ProviderVertexAI, Model: "gemini-2.5-flash", Region: "global",
})
// This step binds the adapter using Application Default Credentials.
_, err := metaagent.NewWithTarget[*request](context.Background(), target, metaagent.Config[*response, toolcall.EmptyTools]{
	UserPrompt: promptbuilder.MustNewPrompt("Answer the request."),
	Tools:      toolcall.NewEmptyToolsProvider[*response](),
})
if err != nil {
	fmt.Println(err)
}

ExampleNewAnthropicDirectMessagesAdapter demonstrates binding an explicit Anthropic workload identity federation configuration to a typed Messages adapter. The route plan remains separate and secret-free.

package main

import (
	"chainguard.dev/driftlessaf/agents/anthropicauth"
	"chainguard.dev/driftlessaf/agents/metaagent"
)

func main() {
	adapter, err := metaagent.NewAnthropicDirectMessagesAdapter(anthropicauth.Config{
		FederationRuleID: "fdrl_0123456789",
		OrganizationID:   "12345678-1234-1234-1234-123456789012",
		Source:           anthropicauth.SourceGoogle,
	})
	if err != nil {
		return
	}
	_ = adapter
}

Output:

ExampleNewBedrockAnthropicMessagesAdapter demonstrates binding explicit AWS IAM Identity Center configuration to a typed Bedrock Messages adapter.

package main

import (
	"chainguard.dev/driftlessaf/agents/awsauth"
	"chainguard.dev/driftlessaf/agents/metaagent"
)

func main() {
	adapter, err := metaagent.NewBedrockAnthropicMessagesAdapter(awsauth.Config{
		Region:  "us-east-1",
		Profile: "engineering-sso",
	})
	if err != nil {
		return
	}
	_ = adapter
}

Output:

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/awsauth"
	"chainguard.dev/driftlessaf/agents/metaagent"
)

func main() {
	adapter, err := metaagent.NewBedrockRuntimeAnthropicMessagesAdapter(awsauth.Config{
		Region:  "us-west-2",
		Profile: "approved-sso-profile",
	})
	fmt.Println(adapter != nil, err)
	// Construction does not load credentials or invoke a model. Register this
	// adapter for ProviderAWSBedrock in the Anthropic Messages registry, using
	// an application-owned route with the exact approved inference profile ID.
	

Output:

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/anthropicauth"
	"chainguard.dev/driftlessaf/agents/metaagent"
)

func main() {
	_, err := metaagent.NewRuntime(nil, metaagent.AnthropicBackend("", anthropicauth.Config{FederationRuleID: "rule", OrganizationID: "org"}))
	fmt.Println(err)
}

Output:
<nil>

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/awsauth"
	"chainguard.dev/driftlessaf/agents/metaagent"
)

func main() {
	_, err := metaagent.NewRuntime(nil, metaagent.BedrockBackend("", awsauth.Config{Region: "us-east-1"}))
	fmt.Println(err)
}

Output:
<nil>

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/metaagent"
)

func main() {
	calls := 0
	backend := metaagent.NewAdapterBackend("account", "example-provider", func(region string) (metaagent.AdapterRegistrations, error) {
		calls++
		// Return adapters capturing this account's configuration and region.
		return metaagent.AdapterRegistrations{}, nil
	})
	_, err := metaagent.NewRuntime(nil, backend)
	fmt.Println(calls, err)
}

Output:
0 <nil>

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/metaagent"
)

func main() {
	_, err := metaagent.NewRuntime(nil, metaagent.VertexBackend("primary", metaagent.VertexConfig{ProjectID: "my-project"}))
	fmt.Println(err)
}

Output:
<nil>

ExampleNewBedrockOpenAIChatCompletionsAdapter constructs an adapter without loading credentials or invoking a model. Register it with a test-only route after independently verifying the account's provider model ID and access.

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/awsauth"
	"chainguard.dev/driftlessaf/agents/metaagent"
	"chainguard.dev/driftlessaf/agents/modelrouter"
)

func main() {
	adapter, err := metaagent.NewBedrockOpenAIChatCompletionsAdapter(awsauth.Config{
		Region:  "us-east-1",
		Profile: "engineering-sso",
	})
	if err != nil {
		fmt.Println(err)
		return
	}
	_, err = metaagent.NewOpenAIChatCompletionsAdapterRegistry(metaagent.OpenAIChatCompletionsRegistration{
		Provider: modelrouter.ProviderAWSBedrock,
		Adapter:  adapter,
	})
	fmt.Println(err)
}

Output:
<nil>

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/awsauth"
	"chainguard.dev/driftlessaf/agents/metaagent"
)

func main() {
	// Omit Profile in workloads using the approved web-identity configuration.
	// Construction validates configuration without discovering credentials.
	_, err := metaagent.NewBedrockOpenAIResponsesAdapter(awsauth.Config{Region: "us-west-2", Profile: "approved-sso-profile"})
	fmt.Println(err)
}

Output:
<nil>

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/metaagent"
)

func main() {
	// Credentials are discovered only when a route binds the service.
	_, err := metaagent.NewVertexOpenAIResponsesAdapter("example-project", "global")
	fmt.Println(err)
}

Output:
<nil>

package main

import (
	"context"
	"fmt"

	"chainguard.dev/driftlessaf/agents/metaagent"
	"chainguard.dev/driftlessaf/agents/modelrouter"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	// Supply an authenticated service in the application adapter. This example
	// only registers it: neither credentials nor network are accessed here.
	adapter := func(_ context.Context, plan modelrouter.Plan) (metaagent.OpenAIResponsesBinding, error) {
		return metaagent.NewOpenAIResponsesBinding(plan, responses.ResponseService{}, nil)
	}
	_, err := metaagent.NewOpenAIResponsesAdapterRegistry(metaagent.OpenAIResponsesRegistration{Provider: "test-provider", Adapter: adapter})
	fmt.Println(err)
}

Output:
<nil>

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/metaagent"
	"chainguard.dev/driftlessaf/agents/modelrouter"
	"github.com/openai/openai-go/v3/responses"
)

func main() {
	selection := modelrouter.Selection{Provider: "test-provider", LogicalModel: "gpt-5.6-sol"}
	routes, err := modelrouter.NewRegistry(modelrouter.Route{Selection: selection, Protocol: modelrouter.ProtocolOpenAIResponses, ProviderModelID: "fixture-deployment", Attribution: modelrouter.Attribution{ProviderName: "test-provider", LegacySystem: "test-provider"}})
	if err != nil {
		panic(err)
	}
	plan, err := routes.Resolve(selection)
	if err != nil {
		panic(err)
	}
	binding, err := metaagent.NewOpenAIResponsesBinding(plan, responses.ResponseService{}, map[string]string{"region": "fixture"})
	if err != nil {
		panic(err)
	}
	_ = binding.Responses() // A typed service, not a Chat Completions client.
	fmt.Println(binding.Plan().Protocol(), binding.ResourceLabels()["region"])
}

Output:
openai-responses fixture

ExampleAsResumer demonstrates obtaining the opt-in resume capability from a constructed agent. AsResumer reports false when the agent's backend does not support suspend/resume, so a waker can branch to a fresh run instead of assuming every backend can wake a checkpoint. Today only the Claude backend (Config.SuspendToolName set) yields a Resumer.

package main

import (
	"context"
	"fmt"

	"chainguard.dev/driftlessaf/agents/metaagent"
	"chainguard.dev/driftlessaf/agents/promptbuilder"
	"chainguard.dev/driftlessaf/agents/toolcall"
)

// request is an example request type that implements promptbuilder.Bindable.
type request struct {
	Query string
}

func (r *request) Bind(p *promptbuilder.Prompt) (*promptbuilder.Prompt, error) {
	return p.BindXML("query", struct {
		XMLName struct{} `xml:"query"`
		Content string   `xml:",chardata"`
	}{
		Content: r.Query,
	})
}

// response is an example structured response type.
type response struct {
	Answer string `json:"answer"`
}

// executeOnly is an Agent without the Resume capability, standing in for a
// backend that has not grown suspend/resume support yet.
type executeOnly struct{}

func (executeOnly) Execute(context.Context, *request, toolcall.EmptyTools) (*response, error) {
	return &response{}, nil
}

func main() {
	var agent metaagent.Agent[*request, *response, toolcall.EmptyTools] = executeOnly{}

	if resumer, ok := metaagent.AsResumer[*request](agent); ok {
		// Resume the parked conversation: answers are keyed by the pending
		// tool-call IDs persisted in the envelope (Envelope.PendingToolCalls).
		_ = resumer
		fmt.Println("resumable")
	} else {
		fmt.Println("not resumable: run from scratch")
	}
}

Output:
not resumable: run from scratch

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/awsauth"
	"chainguard.dev/driftlessaf/agents/metaagent"
	"chainguard.dev/driftlessaf/agents/modelrouter"
)

func main() {
	// Supply exact routes validated for your AWS account and selected API.
	route := modelrouter.Route{
		Selection:       modelrouter.Selection{Provider: modelrouter.ProviderAWSBedrock, LogicalModel: "claude-sonnet-4-6"},
		Protocol:        modelrouter.ProtocolAnthropicMessages,
		ProviderModelID: "anthropic.claude-sonnet-4-6",
		Attribution:     modelrouter.Attribution{ProviderName: "aws.bedrock", LegacySystem: "aws.bedrock"},
		Capabilities:    modelrouter.Capabilities{ToolCalling: true, TerminalSubmission: true},
	}
	_, err := metaagent.NewBedrockRuntimeRouter(awsauth.Config{Region: "us-east-1", Profile: "development"}, route)
	fmt.Println(err)
}

Output:
<nil>

ExampleNewRouterWithAdapters registers explicit Anthropic-direct configuration without separate registry construction or environment-driven routing.

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/anthropicauth"
	"chainguard.dev/driftlessaf/agents/metaagent"
	"chainguard.dev/driftlessaf/agents/modelrouter"
)

func main() {
	selection := modelrouter.Selection{Provider: modelrouter.ProviderAnthropic, LogicalModel: "claude-sonnet-4-6"}
	routes, err := modelrouter.NewRegistry(modelrouter.Route{
		Selection:       selection,
		Protocol:        modelrouter.ProtocolAnthropicMessages,
		ProviderModelID: "claude-sonnet-4-6",
		Attribution:     modelrouter.Attribution{ProviderName: "anthropic", LegacySystem: "anthropic"},
		Capabilities:    modelrouter.Capabilities{ToolCalling: true, TerminalSubmission: true},
	})
	if err != nil {
		panic(err)
	}
	adapter, err := metaagent.NewAnthropicDirectMessagesAdapter(anthropicauth.Config{
		FederationRuleID: "fdrl_0123456789",
		OrganizationID:   "12345678-1234-1234-1234-123456789012",
		Source:           anthropicauth.SourceGoogle,
	})
	if err != nil {
		panic(err)
	}
	router, err := metaagent.NewRouterWithAdapters(routes, metaagent.AdapterRegistrations{
		AnthropicMessages: []metaagent.AnthropicMessagesRegistration{{Provider: selection.Provider, Adapter: adapter}},
	})
	if err != nil {
		panic(err)
	}
	resolution, err := router.Resolve(selection)
	if err != nil {
		panic(err)
	}
	fmt.Println(resolution.Plan().Provider())
}

Output:
anthropic

ExampleNewVertexRouter constructs a shared router without loading credentials. In mono, obtain the declaration from models.LookupRoute instead of duplicating fleet capabilities in application code.

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/metaagent"
	"chainguard.dev/driftlessaf/agents/modelrouter"
)

func main() {
	declaration := exampleVertexDeclaration()
	router, err := metaagent.NewVertexRouter("my-project", "global", declaration)
	if err != nil {
		panic(err)
	}
	resolution, err := router.Resolve(declaration.Selection)
	if err != nil {
		panic(err)
	}
	fmt.Println(resolution.Plan().ProviderModelID())
}

func exampleVertexDeclaration() modelrouter.Route {
	return modelrouter.Route{
		Selection:       modelrouter.Selection{Provider: modelrouter.ProviderVertexAI, LogicalModel: "claude-sonnet-4-6"},
		Protocol:        modelrouter.ProtocolAnthropicMessages,
		ProviderModelID: "claude-sonnet-4-6",
		Attribution:     modelrouter.Attribution{ProviderName: "gcp.vertex_ai", LegacySystem: "google.vertex"},
		Capabilities:    modelrouter.Capabilities{ToolCalling: true, TerminalSubmission: true},
	}
}

Output:
claude-sonnet-4-6

package main

import (
	"fmt"

	"chainguard.dev/driftlessaf/agents/metaagent"
	"chainguard.dev/driftlessaf/agents/modelrouter"
)

func exampleRuntime() *metaagent.Runtime {
	runtime, err := metaagent.NewRuntime([]modelrouter.Route{{
		Selection:       modelrouter.Selection{Provider: modelrouter.ProviderVertexAI, LogicalModel: "gemini-2.5-flash"},
		Protocol:        modelrouter.ProtocolGoogleGenAI,
		ProviderModelID: "gemini-2.5-flash",
		Attribution:     modelrouter.Attribution{ProviderName: "gcp.vertex_ai", LegacySystem: "google.vertex"},
		Capabilities:    modelrouter.Capabilities{ToolCalling: true, TerminalSubmission: true},
	}}, metaagent.VertexBackend("", metaagent.VertexConfig{ProjectID: "my-project"}))
	if err != nil {
		panic(err)
	}
	return runtime
}

func main() {
	runtime := exampleRuntime()
	config := metaagent.TargetConfig{Provider: modelrouter.ProviderVertexAI, Model: "gemini-2.5-flash", Region: "global"}
	first, selection, err := runtime.Target(config).Resolve()
	if err != nil {
		panic(err)
	}
	second, _, err := runtime.Target(config).Resolve()
	if err != nil {
		panic(err)
	}
	fmt.Println(selection.Provider, selection.LogicalModel, first == second)
}

Output:
vertex gemini-2.5-flash true