interfaces

type A2AAgentCard struct {
	// Name is the human-readable agent name.
	Name string `json:"name"`
	// Description summarises what the agent does.
	Description string `json:"description,omitempty"`
	// Version is the agent's own version string.
	Version string `json:"version,omitempty"`
	// URL is the base endpoint of the agent server.
	URL string `json:"url"`
	// DocumentationURL is an optional link to agent documentation.
	DocumentationURL string `json:"documentationUrl,omitempty"`
	// Skills lists the capabilities the agent advertises.
	Skills []A2ASkillSpec `json:"skills,omitempty"`
	// InputModes lists MIME types or mode tokens the agent accepts (e.g. "text/plain", "application/json").
	InputModes []string `json:"defaultInputModes,omitempty"`
	// OutputModes lists MIME types or mode tokens the agent produces.
	OutputModes []string `json:"defaultOutputModes,omitempty"`
}

type A2AArtifact struct {
	// ArtifactID is an optional server-assigned identifier.
	ArtifactID string `json:"artifactId,omitempty"`
	// Name is a human-readable label for the artifact.
	Name string `json:"name,omitempty"`
	// Parts holds the artifact content.
	Parts []A2APart `json:"parts,omitempty"`
	// Metadata holds optional key/value annotations.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type A2AClient interface {
	// Name identifies this connection for logging and tool prefixes (e.g. agent config key).
	Name() string
	// Ping checks that the agent server is reachable. The implementation should use a lightweight
	// check (e.g. fetching the agent card or a health endpoint) with a short-lived connection.
	Ping(ctx context.Context) error
	// ResolveCard fetches the AgentCard from the server's well-known endpoint.
	// It describes the agent's identity, capabilities, and supported input/output modes.
	ResolveCard(ctx context.Context) (A2AAgentCard, error)
	// ListSkills returns the skill specs derived from the agent's AgentCard.
	// Skills are the A2A equivalent of tools: each represents an invocable capability.
	ListSkills(ctx context.Context) ([]A2ASkillSpec, error)
	// SendMessage sends a message to the agent and returns the result.
	// The result is either a completed Message or a Task (when the agent handles the request asynchronously).
	SendMessage(ctx context.Context, req A2ASendMessageRequest) (A2ASendMessageResult, error)
	// Close releases the connection or session.
	Close() error
}

type A2AMessage struct {
	// MessageID is an optional client-assigned identifier for this message.
	MessageID string `json:"messageId,omitempty"`
	// Role is "user" or "agent".
	Role string `json:"role"`
	// Parts holds the content of the message as an ordered slice of heterogeneous parts.
	Parts []A2APart `json:"parts"`
	// Metadata holds optional protocol-level key/value annotations.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type A2APart struct {
	// Kind discriminates the part type: "text", "data", or "file".
	Kind string `json:"kind"`
	// Text holds the content when Kind is "text".
	Text string `json:"text,omitempty"`
	// Data holds structured JSON content when Kind is "data".
	Data json.RawMessage `json:"data,omitempty"`
	// FileMIMEType is the MIME type hint when Kind is "file".
	FileMIMEType string `json:"fileMimeType,omitempty"`
	// FileBytes holds base64-encoded file content when Kind is "file".
	FileBytes string `json:"fileBytes,omitempty"`
	// FileURI holds a URI reference to file content when Kind is "file".
	FileURI string `json:"fileUri,omitempty"`
}

type A2ASendMessageRequest struct {
	// Message is the user-turn message to send.
	Message A2AMessage `json:"message"`
	// TaskID optionally resumes an existing async task.
	TaskID string `json:"taskId,omitempty"`
	// SessionID optionally groups related tasks into a logical session.
	SessionID string `json:"sessionId,omitempty"`
	// AcceptedOutputModes lists the output modes the caller can handle.
	// If empty, the agent uses its default output modes.
	AcceptedOutputModes []string `json:"acceptedOutputModes,omitempty"`
}

type A2ASendMessageResult struct {
	// Message is set when the agent returned a complete message response inline.
	Message *A2AMessage `json:"message,omitempty"`
	// Task is set when the agent created or updated an async task.
	Task *A2ATask `json:"task,omitempty"`
}

type A2ASkillSpec = types.A2ASkillSpec

type A2AStreamEvent struct {
	// Kind discriminates the event type: "message", "taskStatus", or "artifact".
	Kind string `json:"kind"`
	// TaskID is the server-assigned task ID; present on all event kinds.
	TaskID string `json:"taskId,omitempty"`
	// IsFinal is true on the last event for this stream.
	IsFinal bool `json:"final,omitempty"`
	// Message is set when Kind is "message".
	Message *A2AMessage `json:"message,omitempty"`
	// TaskStatus is set when Kind is "taskStatus".
	TaskStatus *A2ATaskStatusUpdate `json:"taskStatus,omitempty"`
	// Artifact is set when Kind is "artifact".
	Artifact *A2AArtifact `json:"artifact,omitempty"`
}

type A2AStreamSeq func(yield func(A2AStreamEvent, error) bool)

type A2AStreamingClient interface {
	A2AClient
	// SendStreamingMessage sends a message and returns an iterator over events streamed back by
	// the agent. Each event is either a message delta, a task status update, or an artifact update.
	// The caller must consume or break the iterator to release server-side resources.
	SendStreamingMessage(ctx context.Context, req A2ASendMessageRequest) (A2AStreamSeq, error)
}

type A2ATask struct {
	// ID is the server-assigned task identifier.
	ID string `json:"id"`
	// SessionID is the optional session this task belongs to.
	SessionID string `json:"sessionId,omitempty"`
	// Status is the current lifecycle state of the task.
	Status A2ATaskStatus `json:"status"`
	// Message is the latest agent message associated with this task, if any.
	Message *A2AMessage `json:"message,omitempty"`
	// Artifacts holds any named outputs produced by the task.
	Artifacts []A2AArtifact `json:"artifacts,omitempty"`
	// Metadata holds optional server-supplied key/value annotations.
	Metadata map[string]string `json:"metadata,omitempty"`
}

type A2ATaskClient interface {
	A2AClient
	// GetTask retrieves the current state of an async task by its ID.
	GetTask(ctx context.Context, taskID string) (A2ATask, error)
	// CancelTask requests cancellation of an in-progress task.
	// The returned Task reflects the state after the cancellation request is acknowledged.
	CancelTask(ctx context.Context, taskID string) (A2ATask, error)
}

type A2ATaskStatus string

type A2ATaskStatusUpdate struct {
	// Status is the updated lifecycle state.
	Status A2ATaskStatus `json:"status"`
	// Message is an optional agent message accompanying the status change.
	Message *A2AMessage `json:"message,omitempty"`
}

type AgentToolApprovalPolicy interface {
	RequiresApproval(tool Tool) bool
}

type Attribute struct {
	Key   string
	Value any
}

type Conversation interface {
	// AddMessage adds a message to the conversation identified by id. Id is passed at runtime (e.g. from Run input, workflow).
	AddMessage(ctx context.Context, id string, msg Message) error

	// ListMessages returns messages for the conversation identified by id.
	ListMessages(ctx context.Context, id string, opts ...ListMessagesOption) ([]Message, error)

	// Clear removes all messages for the conversation identified by id. Called by the user when ending a session.
	Clear(ctx context.Context, id string) error

	// IsDistributed returns true if the implementation uses distributed storage (Redis, Postgres, etc.).
	// In-memory implementations return false. Use distributed implementations when using remote workers.
	IsDistributed() bool
}

type Document struct {
	Content  string
	Source   string
	Score    float64
	Metadata map[string]any
}

type JSONSchema = types.JSONSchema

type LLMClient interface {
	// Generate generates a response from the LLM.
	Generate(ctx context.Context, request *LLMRequest) (*LLMResponse, error)
	// GenerateStream generates a response from the LLM using streaming.
	GenerateStream(ctx context.Context, request *LLMRequest) (LLMStream, error)
	// GetModel returns the model name.
	GetModel() string
	// GetProvider returns the provider name.
	GetProvider() LLMProvider
	// IsStreamSupported returns true if the client supports streaming (e.g. OpenAI, Anthropic).
	IsStreamSupported() bool
}

type LLMProvider string

type LLMReasoning = types.LLMReasoning

type LLMRequest struct {
	SystemMessage  string
	ResponseFormat *ResponseFormat
	Tools          []ToolSpec // Tool specs for the LLM to choose from
	// Messages is the conversation history. For first turn, use one user message.
	// For continuation after tool use: append assistant (with ToolCalls) + tool result messages.
	Messages []Message

	// Sampling (per-request; typically set from agent config). nil/0 = provider default.
	Temperature *float64 // 0-2 OpenAI, 0-1 Anthropic; also Gemini
	MaxTokens   int      // 0 = provider default
	TopP        *float64 // 0-1; OpenAI and Gemini (Anthropic client does not set TopP)
	TopK        *int     // Anthropic only

	// Reasoning configures generic reasoning/thinking when non-nil; each LLM client maps fields to its API.
	Reasoning *LLMReasoning
}

type LLMResponse struct {
	Content  string
	Metadata map[string]any
	// Usage is set when the provider returns token usage for this completion (non-stream and stream).
	Usage *LLMUsage
	// ToolCalls contains any tool invocations the LLM chose; empty when none.
	ToolCalls []*ToolCall
}

type LLMStream interface {
	Next() bool
	Current() *LLMStreamChunk
	Err() error
	// GetResult returns the accumulated content and tool calls after streaming completes.
	// Call after the Next loop; returns nil if streaming failed or was not completed.
	GetResult() *LLMResponse
}

type LLMStreamChunk struct {
	ContentDelta  string      // partial text content
	ThinkingDelta string      // Anthropic extended thinking (optional)
	ToolCalls     []*ToolCall // set on final chunk when tool calls are present
}

type LLMUsage = types.LLMUsage

type ListMessagesOption func(*ListMessagesOptions)

type ListMessagesOptions struct {
	// Limit is the maximum number of messages to retrieve from recent. -1 = all.
	Limit int

	// Offset is the number of most recent messages to skip. -1 = 0 (default).
	Offset int

	// Roles filters messages by role
	Roles []MessageRole
}

type LoadMemoryOption func(*LoadMemoryOptions)

type LoadMemoryOptions struct {
	// Limit is the maximum number of memories to return. Zero or negative means backend default.
	Limit int

	// MinScore filters out entries below the given relevance score when Score is applicable.
	MinScore float32

	// Kinds restricts recall to the given memory kinds. Empty means all kinds.
	Kinds []MemoryKind
}

type Logs interface {
	// Shutdown flushes buffered log records and releases the exporter connection.
	Shutdown(ctx context.Context) error
}

type MCPClient interface {
	// Name identifies this connection for logging and tool prefixes (e.g. [github.com/agenticenv/agent-sdk-go/pkg/agent.MCPServers] key or [github.com/agenticenv/agent-sdk-go/pkg/mcp/client.NewClient] first argument).
	Name() string
	// Ping checks that the server responds (MCP ping on a short-lived session). The default
	// implementation connects, pings, and disconnects; ListTools and CallTool each open their own session.
	Ping(ctx context.Context) error
	// ListTools returns tool definitions from the server (tools/list).
	ListTools(ctx context.Context) ([]ToolSpec, error)
	// CallTool invokes a tool by name with JSON arguments (tools/call).
	CallTool(ctx context.Context, tool string, input json.RawMessage) (json.RawMessage, error)
	// Close releases the connection or session.
	Close() error
}

type MCPPromptClient interface {
	MCPClient
	// ListPrompts returns available prompts (prompts/list).
	ListPrompts(ctx context.Context) ([]PromptSpec, error)
	// GetPrompt resolves a prompt template with arguments (prompts/get).
	GetPrompt(ctx context.Context, name string, args map[string]string) (json.RawMessage, error)
}

type MCPResourceClient interface {
	MCPClient
	// ListResources returns available resources (resources/list).
	ListResources(ctx context.Context) ([]ResourceSpec, error)
	// ReadResource returns the resource body for uri (resources/read).
	ReadResource(ctx context.Context, uri string) (json.RawMessage, error)
}

type Memory interface {
	// Store persists a new memory in the given scope and returns its assigned ID.
	// The returned ID is always non-empty; implementations must assign one if the
	// backend does not (e.g. a UUID).
	//
	// Expiry (ExpiresAt on [MemoryRecord]) is set by the agent SDK from TTL policy.
	// Use [WithMemoryID] to upsert an existing record.
	Store(ctx context.Context, scope MemoryScope, record MemoryRecord, opts ...StoreMemoryOption) (id string, err error)

	// Load retrieves memories within scope.
	// Query drives ranking or filtering; pass empty query to list by recency when supported.
	// Implementations must omit expired entries (ExpiresAt non-zero and in the past).
	//
	// Non-empty scope fields filter results (AND). Use [WithLoadLimit], [WithMinScore],
	// and [WithLoadKinds] to narrow recall.
	Load(ctx context.Context, scope MemoryScope, query string, opts ...LoadMemoryOption) ([]MemoryEntry, error)

	// Clear removes all memories matching the scope. Called by the application when
	// required (e.g. user offboarding). Not invoked by the agent runtime.
	// Warning: a TenantID-only scope deletes all memories for that tenant across every user and agent.
	Clear(ctx context.Context, scope MemoryScope) error
}

type MemoryEntry struct {
	// ID is the stable record identifier assigned by the backend.
	// Always non-empty; required for upserts via [WithMemoryID].
	ID string

	Text      string
	Kind      MemoryKind
	Scope     MemoryScope
	Metadata  map[string]string
	ExpiresAt time.Time

	// Score is query relevance when the backend supports ranked retrieval (e.g. vector search).
	// Zero means not applicable (e.g. key-value or recency-only backends).
	Score float32

	CreatedAt time.Time
	UpdatedAt time.Time
}

type MemoryKind string

type MemoryRecord struct {
	// Text is the distilled fact, preference, or instruction to remember.
	Text string

	// Kind is an optional category label for filtered recall. Empty is allowed.
	Kind MemoryKind

	// Metadata holds optional attributes (source run, confidence, custom tags).
	// Scope fields from [MemoryScope] are stored separately and should not be duplicated here.
	Metadata map[string]string

	// ExpiresAt is when the entry should no longer be recalled. Zero means no expiry.
	// The agent SDK sets this from [memory.Config] TTL policy on Store; direct callers may leave it zero.
	ExpiresAt time.Time
}

type MemoryScope struct {
	UserID   string
	TenantID string
	AgentID  string

	// Tags holds additional scope dimensions (e.g. project, team, environment).
	// Do not duplicate UserID, TenantID, or AgentID as tag keys.
	Tags map[string]string
}

type Message struct {
	Role    MessageRole `json:"role"`
	Content string      `json:"content"`

	ToolName   string      `json:"tool_name"`
	ToolCallID string      `json:"tool_call_id"`
	ToolCalls  []*ToolCall `json:"tool_calls"`

	Metadata  map[string]any `json:"metadata"`
	CreatedAt time.Time      `json:"created_at"`
}

type MessageRole string

type Metrics interface {
	// IncrementCounter adds one to a named counter with optional attributes.
	IncrementCounter(ctx context.Context, name string, attrs ...Attribute)

	// RecordHistogram records a sample on a histogram-style instrument.
	RecordHistogram(ctx context.Context, name string, value float64, attrs ...Attribute)

	// Shutdown flushes exporters and releases resources when the agent or worker stops.
	Shutdown(ctx context.Context) error
}

type OTelTracer interface {
	// OTelTracer returns the underlying OpenTelemetry Tracer.
	OTelTracer() trace.Tracer
}

type PromptSpec struct {
	Name        string `json:"name"`                  // Prompt identifier.
	Description string `json:"description,omitempty"` // Short description.
}

type ResourceSpec struct {
	URI         string `json:"uri"`                   // Resource URI.
	Name        string `json:"name,omitempty"`        // Human-readable name.
	Description string `json:"description,omitempty"` // Short description.
	MimeType    string `json:"mimeType,omitempty"`    // Optional MIME type hint.
}

type ResponseFormat struct {
	Type   ResponseFormatType
	Name   string
	Schema JSONSchema
}

type ResponseFormatType string

type Retriever interface {
	// Name returns the unique name of the retriever.
	Name() string
	// Search searches the retriever for documents matching the query.
	Search(ctx context.Context, query string) ([]Document, error)
}

type Span interface {
	// End completes the span; safe to call once.
	End()

	// SetAttribute attaches a typed attribute to this span.
	SetAttribute(key string, value any)

	// RecordError records err on the span when non-nil.
	RecordError(err error)
}

type StoreMemoryOption func(*StoreMemoryOptions)

type StoreMemoryOptions struct {
	// ID upserts the record when non-empty. Use the ID returned by a prior Store call.
	ID string
}

type Tool interface {
	// Name returns the tool identifier (e.g. "search", "calculator"). Used by the LLM in tool calls.
	Name() string

	// DisplayName returns the tool display name (e.g. "Search", "Calculator"). Used by the LLM in tool calls.
	DisplayName() string

	// Description describes when and how to use this tool. Shown to the LLM for tool selection.
	Description() string

	// Parameters returns the JSON schema for the tool's input. The LLM produces args matching this schema.
	// Use tools.Params with tools.ParamString, ParamInteger, etc. for type-safe construction.
	Parameters() JSONSchema

	// Execute runs the tool with the given args. Args match the Parameters schema.
	// Called by the agent when the LLM returns a tool call for this tool.
	Execute(ctx context.Context, args map[string]any) (any, error)
}

type ToolApproval interface {
	ApprovalRequired() bool
}

type ToolAuthorizationDecision struct {
	Allow  bool   `json:"allow"`
	Reason string `json:"reason,omitempty"`
}

type ToolAuthorizer interface {
	Authorize(ctx context.Context, args map[string]any) (ToolAuthorizationDecision, error)
}

type ToolCall struct {
	ToolCallID string         `json:"tool_call_id"` // from API; needed to match tool results
	ToolName   string         `json:"tool_name"`
	Args       map[string]any `json:"args"`
}

type ToolSpec = types.ToolSpec

type Tracer interface {
	// StartSpan creates a span named name and returns a context that carries it plus the span handle.
	StartSpan(ctx context.Context, name string, attrs ...Attribute) (context.Context, Span)

	// Shutdown flushes exporters and releases resources when the agent or worker stops.
	Shutdown(ctx context.Context) error
}