agentcore

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Jan 5, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package agentcore provides a runtime adapter for AWS Bedrock AgentCore.

AgentCore is AWS's serverless runtime for AI agents, providing:

  • Firecracker microVM isolation per session
  • Automatic scaling from zero
  • Built-in session memory and identity
  • Pay-per-use pricing (only active CPU time)

This package implements the AgentCore HTTP contract (/ping, /invocations) and allows AgentKit agents to run on AgentCore without code changes.

Note: Helm/Kubernetes configuration does NOT apply to AgentCore. Use AWS CDK, CloudFormation, or Terraform for AgentCore deployment.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewSessionContext 

func NewSessionContext(ctx context.Context, sessionID string, req *Request) context.Context

NewSessionContext creates a context with session and request information. This is a convenience function that combines WithSession and WithRequest.

func SessionID 

func SessionID(ctx context.Context) string

SessionID retrieves the session ID from the context. Returns empty string if no session is present.

func SessionMetadata 

func SessionMetadata(ctx context.Context, key string) string

SessionMetadata retrieves a metadata value from the session. Returns empty string if the key doesn't exist or no session is present.

func WithRequest 

func WithRequest(ctx context.Context, req *Request) context.Context

WithRequest adds the original request to the context. Useful for agents that need access to the full request.

func WithSession 

func WithSession(ctx context.Context, session *Session) context.Context

WithSession adds session information to the context.

Types

type ADKAgentAdapter 

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

ADKAgentAdapter wraps a Google ADK agent for AgentCore. Note: This is a placeholder - actual implementation depends on ADK's Go API.

func NewADKAgentAdapter 

func NewADKAgentAdapter(cfg ADKAgentConfig) *ADKAgentAdapter

NewADKAgentAdapter creates an Agent that wraps a Google ADK agent.

func (*ADKAgentAdapter) Invoke 

func (a *ADKAgentAdapter) Invoke(ctx context.Context, req Request) (Response, error)

Invoke calls the underlying ADK agent.

func (*ADKAgentAdapter) Name 

func (a *ADKAgentAdapter) Name() string

Name returns the agent name.

type ADKAgentConfig 

type ADKAgentConfig struct {
	Name        string
	Description string
	// Invoke is the function that calls the ADK agent.
	// This abstraction allows different ADK agent implementations.
	Invoke func(ctx context.Context, prompt string) (string, error)
}

ADKAgentConfig configures an ADKAgentAdapter.

type Agent 

type Agent interface {
	// Name returns the unique identifier for this agent.
	// Used for routing in multi-agent setups.
	Name() string

	// Invoke processes a request and returns a response.
	// The context carries session information and cancellation signals.
	Invoke(ctx context.Context, req Request) (Response, error)
}

Agent is the interface that AgentCore-compatible agents must implement. This interface is designed to be simple and runtime-agnostic.

type AgentFunc 

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

AgentFunc is a function type that implements the Agent interface. Useful for simple agents that don't need state.

func NewAgentFunc 

func NewAgentFunc(name string, fn func(ctx context.Context, req Request) (Response, error)) *AgentFunc

NewAgentFunc creates an Agent from a function.

func (*AgentFunc) Invoke 

func (a *AgentFunc) Invoke(ctx context.Context, req Request) (Response, error)

Invoke calls the underlying function.

func (*AgentFunc) Name 

func (a *AgentFunc) Name() string

Name returns the agent name.

type Builder 

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

Builder provides a fluent interface for building an AgentCore server.

func NewBuilder 

func NewBuilder() *Builder

NewBuilder creates a new server builder.

func (*Builder) Build 

func (b *Builder) Build(ctx context.Context) (*Server, error)

Build creates the server and registers all agents.

func (*Builder) MustBuild 

func (b *Builder) MustBuild(ctx context.Context) *Server

MustBuild is like Build but panics on error.

func (*Builder) WithAgent 

func (b *Builder) WithAgent(agent Agent) *Builder

WithAgent adds an agent to the server.

func (*Builder) WithAgents 

func (b *Builder) WithAgents(agents ...Agent) *Builder

WithAgents adds multiple agents to the server.

func (*Builder) WithConfig 

func (b *Builder) WithConfig(cfg Config) *Builder

WithConfig sets the server configuration.

func (*Builder) WithDefaultAgent 

func (b *Builder) WithDefaultAgent(name string) *Builder

WithDefaultAgent sets the default agent name.

func (*Builder) WithPort 

func (b *Builder) WithPort(port int) *Builder

WithPort sets the server port.

func (*Builder) WithRegistry 

func (b *Builder) WithRegistry(registry *Registry) *Builder

WithRegistry uses an existing registry instead of creating a new one.

type Closer 

type Closer interface {
	// Close releases resources held by the agent.
	Close() error
}

Closer is an optional interface for agents that need cleanup. Called when the server is shutting down.

type Config 

type Config struct {
	// Port is the port to listen on. Default is 8080 (AgentCore standard).
	Port int

	// ReadTimeout is the maximum duration for reading requests.
	// Default is 30 seconds.
	ReadTimeout time.Duration

	// WriteTimeout is the maximum duration for writing responses.
	// Default is 300 seconds (5 minutes) for long-running agent operations.
	WriteTimeout time.Duration

	// IdleTimeout is the maximum time to wait for the next request.
	// Default is 60 seconds.
	IdleTimeout time.Duration

	// DefaultAgent is the agent to use when no agent is specified in the request.
	// If empty, the "agent" field is required in invocation requests.
	DefaultAgent string

	// EnableRequestLogging enables logging of incoming requests.
	// Default is true.
	EnableRequestLogging bool

	// EnableSessionTracking enables session ID tracking in logs.
	// Default is true.
	EnableSessionTracking bool
}

Config holds configuration for an AgentCore runtime server.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns a Config with sensible defaults for AgentCore.

func LoadConfigFromEnv 

func LoadConfigFromEnv() Config

LoadConfigFromEnv loads configuration from environment variables. Environment variables:

  • AGENTCORE_PORT: Port to listen on (default: 8080)
  • AGENTCORE_DEFAULT_AGENT: Default agent name
  • AGENTCORE_READ_TIMEOUT_SECS: Read timeout in seconds
  • AGENTCORE_WRITE_TIMEOUT_SECS: Write timeout in seconds
  • AGENTCORE_ENABLE_REQUEST_LOGGING: Enable request logging (true/false)

type ExecutorAdapter 

type ExecutorAdapter[I, O any] struct {
	// contains filtered or unexported fields
}

ExecutorAdapter wraps an AgentKit Executor to implement the Agent interface. This allows Eino-based workflows to run on AgentCore without modification.

func NewExecutorAdapter 

func NewExecutorAdapter[I, O any](cfg ExecutorAdapterConfig[I, O]) *ExecutorAdapter[I, O]

NewExecutorAdapter creates an Agent that wraps an AgentKit Executor.

func WrapExecutor 

func WrapExecutor[I, O any](name string, executor *orchestration.Executor[I, O]) *ExecutorAdapter[I, O]

WrapExecutor is a convenience function to create an ExecutorAdapter with defaults. Uses JSON for input parsing and output formatting.

func WrapExecutorWithPrompt 

func WrapExecutorWithPrompt[I, O any](
	name string,
	executor *orchestration.Executor[I, O],
	setPrompt func(prompt string) I,
	getOutput func(output O) string,
) *ExecutorAdapter[I, O]

WrapExecutorWithPrompt creates an adapter where the prompt is passed directly to a field in the input struct. Useful for simple prompt-in/response-out agents.

func (*ExecutorAdapter[I, O]) Invoke 

func (a *ExecutorAdapter[I, O]) Invoke(ctx context.Context, req Request) (Response, error)

Invoke executes the wrapped Executor.

func (*ExecutorAdapter[I, O]) Name 

func (a *ExecutorAdapter[I, O]) Name() string

Name returns the agent name.

type ExecutorAdapterConfig 

type ExecutorAdapterConfig[I, O any] struct {
	// Name is the agent name for routing.
	Name string

	// Executor is the AgentKit Executor to wrap.
	Executor *orchestration.Executor[I, O]

	// ParseInput converts the prompt string to the executor's input type.
	// If nil, JSON unmarshaling is used.
	ParseInput func(prompt string) (I, error)

	// FormatOutput converts the executor's output to a response string.
	// If nil, JSON marshaling is used.
	FormatOutput func(output O) string
}

ExecutorAdapterConfig configures an ExecutorAdapter.

type HandlerAdapter 

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

HandlerAdapter wraps an http.HandlerFunc-style function as an Agent. Useful for migrating existing HTTP handlers to AgentCore.

func NewHandlerAdapter 

func NewHandlerAdapter(name string, handler func(ctx context.Context, req Request) (Response, error)) *HandlerAdapter

NewHandlerAdapter creates an Agent from a handler function.

func (*HandlerAdapter) Invoke 

func (a *HandlerAdapter) Invoke(ctx context.Context, req Request) (Response, error)

Invoke calls the handler function.

func (*HandlerAdapter) Name 

func (a *HandlerAdapter) Name() string

Name returns the agent name.

type HealthChecker 

type HealthChecker interface {
	// HealthCheck returns nil if the agent is healthy, error otherwise.
	HealthCheck(ctx context.Context) error
}

HealthChecker is an optional interface for agents that support health checks. If an agent implements this, the server will call it for /ping requests.

type Initializer 

type Initializer interface {
	// Initialize is called when the agent is registered.
	Initialize(ctx context.Context) error
}

Initializer is an optional interface for agents that need initialization. Called once when the agent is registered with the server.

type MultiAgentRouter 

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

MultiAgentRouter routes requests to multiple agents based on the agent field. This is useful when you want a single AgentCore endpoint to handle multiple agents.

func NewMultiAgentRouter 

func NewMultiAgentRouter(name string, agents ...Agent) (*MultiAgentRouter, error)

NewMultiAgentRouter creates a router that delegates to other agents.

func (*MultiAgentRouter) Invoke 

func (r *MultiAgentRouter) Invoke(ctx context.Context, req Request) (Response, error)

Invoke routes the request to the appropriate agent.

func (*MultiAgentRouter) Name 

func (r *MultiAgentRouter) Name() string

Name returns the router name.

func (*MultiAgentRouter) RegisterAgent 

func (r *MultiAgentRouter) RegisterAgent(ctx context.Context, agent Agent) error

RegisterAgent adds an agent to the router.

type Registry 

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

Registry manages a collection of agents and routes requests to them.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a new agent registry.

func (*Registry) Close 

func (r *Registry) Close() error

Close closes all agents that implement Closer. Collects all errors and returns them as a combined error.

func (*Registry) Count 

func (r *Registry) Count() int

Count returns the number of registered agents.

func (*Registry) Get 

func (r *Registry) Get(name string) (Agent, error)

Get retrieves an agent by name. If name is empty, returns the default agent (if set).

func (*Registry) HealthCheck 

func (r *Registry) HealthCheck(ctx context.Context) map[string]error

HealthCheck checks the health of all agents that implement HealthChecker. Returns a map of agent names to their health status (nil = healthy).

func (*Registry) Invoke 

func (r *Registry) Invoke(ctx context.Context, req Request) (Response, error)

Invoke routes a request to the appropriate agent and invokes it. This is a convenience method that combines Get and Invoke.

func (*Registry) List 

func (r *Registry) List() []string

List returns the names of all registered agents.

func (*Registry) MustRegister 

func (r *Registry) MustRegister(ctx context.Context, agent Agent)

MustRegister is like Register but panics on error. Useful for initialization code where registration should never fail.

func (*Registry) Register 

func (r *Registry) Register(ctx context.Context, agent Agent) error

Register adds an agent to the registry. If the agent implements Initializer, Initialize() is called. Returns an error if an agent with the same name already exists.

func (*Registry) RegisterAll 

func (r *Registry) RegisterAll(ctx context.Context, agents ...Agent) error

RegisterAll registers multiple agents. Stops on the first error.

func (*Registry) SetDefault 

func (r *Registry) SetDefault(name string) error

SetDefault sets the default agent to use when no agent is specified.

type Request 

type Request struct {
	// Prompt is the user's input/query to the agent.
	Prompt string `json:"prompt"`

	// SessionID is the AgentCore session identifier.
	// AgentCore provides session isolation via Firecracker microVMs.
	SessionID string `json:"session_id,omitempty"`

	// Agent specifies which agent to invoke (for multi-agent setups).
	// If empty, the server's DefaultAgent is used.
	Agent string `json:"agent,omitempty"`

	// Metadata contains additional context passed to the agent.
	Metadata map[string]string `json:"metadata,omitempty"`

	// RawInput contains the full raw JSON input for custom parsing.
	// Use this when your agent needs access to fields beyond the standard ones.
	RawInput json.RawMessage `json:"-"`
}

Request represents an AgentCore invocation request. This is passed to agents when /invocations is called.

func RequestFromContext 

func RequestFromContext(ctx context.Context) *Request

RequestFromContext retrieves the original request from the context. Returns nil if no request is present.

type Response 

type Response struct {
	// Output is the agent's response text.
	Output string `json:"output"`

	// Metadata contains additional response metadata.
	Metadata map[string]string `json:"metadata,omitempty"`

	// Error contains error information if the invocation failed.
	// This is separate from HTTP errors for partial failure scenarios.
	Error string `json:"error,omitempty"`
}

Response represents an AgentCore invocation response.

type Server 

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

Server implements the AWS AgentCore HTTP contract. It handles /ping and /invocations endpoints as required by AgentCore Runtime.

func NewServer 

func NewServer(cfg Config) *Server

NewServer creates a new AgentCore server with the given configuration.

func NewServerWithRegistry 

func NewServerWithRegistry(cfg Config, registry *Registry) *Server

NewServerWithRegistry creates a new AgentCore server with a pre-configured registry.

func (*Server) MustRegister 

func (s *Server) MustRegister(ctx context.Context, agent Agent)

MustRegister is like Register but panics on error.

func (*Server) Register 

func (s *Server) Register(ctx context.Context, agent Agent) error

Register adds an agent to the server's registry.

func (*Server) RegisterAll 

func (s *Server) RegisterAll(ctx context.Context, agents ...Agent) error

RegisterAll registers multiple agents.

func (*Server) Registry 

func (s *Server) Registry() *Registry

Registry returns the server's agent registry.

func (*Server) SetDefaultAgent 

func (s *Server) SetDefaultAgent(name string) error

SetDefaultAgent sets the default agent to use when none is specified.

func (*Server) Start 

func (s *Server) Start() error

Start starts the AgentCore server. This method blocks until the server stops.

func (*Server) StartAsync 

func (s *Server) StartAsync()

StartAsync starts the server in the background. Returns immediately. Use Stop() to shut down the server.

func (*Server) Stop 

func (s *Server) Stop(ctx context.Context) error

Stop gracefully shuts down the server and closes all agents.

type Session 

type Session struct {
	// ID is the unique session identifier provided by AgentCore.
	ID string

	// Metadata contains session-level metadata.
	Metadata map[string]string
}

Session represents an AgentCore session context. AgentCore provides session isolation via Firecracker microVMs, with each session getting dedicated CPU, memory, and filesystem resources.

func SessionFromContext 

func SessionFromContext(ctx context.Context) *Session

SessionFromContext retrieves session information from the context. Returns nil if no session is present.

Source Files

View all Source files

Directories

Path Synopsis
Package iac provides shared infrastructure-as-code configuration for AgentCore deployments.
 Package iac provides shared infrastructure-as-code configuration for AgentCore deployments.

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.