research

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package research implements the seven agent roles of the multi-agent research workflow as one Fenced-native runtime. Every role executes inside the fenced attempt context the platform injects: models are invoked through the brokered fenced.model.invoke system tool, side effects go through tenant tools behind the Tool Gateway, artifacts land in namespaced memory, and dynamic fan-out happens through fenced.task.spawn - the runtime never talks to providers, stores or the kernel directly.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CallTenantTool 

func CallTenantTool(ctx context.Context, mcp MCPClient, executionID, name string, args any) (json.RawMessage, error)

CallTenantTool invokes a tenant tool by name through the broker and fails when the tool reports an error outcome (denials, endpoint failures).

func EnvelopePrefix 

func EnvelopePrefix() string

EnvelopePrefix exposes the goal envelope marker to application publishers.

func ExtractUpstreamOutputs 

func ExtractUpstreamOutputs(goal string) map[string]string

ExtractUpstreamOutputs pulls the "Upstream result [step]: <json>" blocks the workflow renderer appends to declared-step goals, so downstream roles can consume dependency outputs without extra transport.

func InvokeModelText 

func InvokeModelText(ctx context.Context, deps Deps, executionID, modelRef, system, user string) (string, error)

func PutMemory 

func PutMemory(ctx context.Context, mcp MCPClient, executionID, namespace, key, contentType string, value any) error

PutMemory writes one record into the workflow's namespace tree.

func RoleFromRef 

func RoleFromRef(versionRef string) string

RoleFromRef maps an agent version reference onto its role name ("research-reader@1" -> "reader").

func Run 

func Run(ctx context.Context, deps Deps, executionID, versionRef, goal string) (json.RawMessage, error)

Run executes one role turn and returns the step output document.

func SpawnChild 

func SpawnChild(ctx context.Context, mcp MCPClient, executionID, name, childRef, goal string, maxAttempts int) error

SpawnChild extends the running workflow with one dynamic step. The child's placement overlay is derived from its role so the child always lands on its runtime class regardless of the spawning parent.

Types

type ChatCall 

type ChatCall struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type ChatMessage 

type ChatMessage struct {
	Role       string     `json:"role"`
	Content    string     `json:"content"`
	ToolCallID string     `json:"toolCallId,omitempty"`
	ToolCalls  []ChatCall `json:"toolCalls,omitempty"`
}

ChatMessage mirrors the brokered message shape.

type ChatTurn 

type ChatTurn struct {
	Content   string
	ToolCalls []ChatCall
}

ChatTurn is one model invocation result.

func InvokeModel 

func InvokeModel(ctx context.Context, mcp MCPClient, executionID, modelRef string, messages []ChatMessage) (ChatTurn, error)

InvokeModel runs one governed model invocation through the broker, resolving the logical tier to this deployment's reference first.

type Claim 

type Claim struct {
	ClaimID    string  `json:"claimId"`
	Claim      string  `json:"claim"`
	Evidence   string  `json:"evidence"`
	Confidence float64 `json:"confidence"`
	// SourceHash pins the exact retrieved source text the evidence was
	// verified against (sha256 hex); Grounded records that verification.
	SourceHash string `json:"sourceHash,omitempty"`
	Grounded   bool   `json:"grounded"`
}

type Deps 

type Deps struct {
	MCP     MCPClient
	Models  Models
	Workdir func(namespace string) string // renders research/{workflow}/{leaf}
}

Deps carries the brokered surfaces every role needs.

type Envelope 

type Envelope struct {
	Role     string     `json:"role"`
	Goal     string     `json:"goal"`
	Workflow string     `json:"workflowId"`
	Round    int        `json:"round,omitempty"`
	Question *Question  `json:"question,omitempty"`
	Source   *SourceHit `json:"source,omitempty"`
	Verdict  string     `json:"upstreamVerdict,omitempty"`
}

Envelope is the structured task payload every role finds inside its goal. The application renders it into each static step's goal and parents embed it into spawned children's goals; the kernel transports it verbatim.

func ParseEnvelope 

func ParseEnvelope(goal, versionRef string) Envelope

ParseEnvelope decodes the structured payload from a goal, tolerating plain goals by falling back to the role implied by the agent version reference. The kernel may append rendered upstream-result blocks AFTER the envelope, so decoding stops at the first JSON value instead of whole-payload parse.

type EvidenceBundle 

type EvidenceBundle struct {
	SourceID           string  `json:"sourceId"`
	ResearchQuestionID string  `json:"researchQuestionId"`
	Title              string  `json:"title"`
	URL                string  `json:"url"`
	Claims             []Claim `json:"claims"`
}

type FetchedDocument 

type FetchedDocument struct {
	SourceID  string `json:"sourceId"`
	Title     string `json:"title"`
	URL       string `json:"url"`
	Content   string `json:"content"`
	FetchedAt string `json:"fetchedAt"`
}

FetchedDocument mirrors the web.fetch tool response payload.

type HTTPMCPClient 

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

HTTPMCPClient posts JSON-RPC tool calls to the runtime's loopback MCP endpoint, carrying the attempt execution id in the fencing header exactly like the reference Python SDK.

func NewHTTPMCPClient 

func NewHTTPMCPClient(endpoint string) *HTTPMCPClient

NewHTTPMCPClient binds the client to the MCP endpoint URL.

func (*HTTPMCPClient) CallTool 

func (c *HTTPMCPClient) CallTool(ctx context.Context, executionID, name string, callArgs any) (json.RawMessage, error)

CallTool implements MCPClient.

type MCPClient 

type MCPClient interface {
	CallTool(ctx context.Context, executionID, name string, args any) (json.RawMessage, error)
}

MCPClient is the brokered tool surface of one attempt. The execution id is the attempt-scoped window key the runtime worker opened for this agent; every call carries it so concurrent attempts stay fenced.

type MCPToolError 

type MCPToolError struct {
	Code    string
	Message string
}

MCPToolError is the bounded, machine-readable failure returned by an MCP tool outcome. Payload preserves the structured document for diagnostics; Code is safe to classify without parsing provider or endpoint prose.

func (*MCPToolError) Error 

func (e *MCPToolError) Error() string

type MemoryRecord 

type MemoryRecord struct {
	ID        string `json:"id"`
	Namespace string `json:"namespace"`
	Key       string `json:"key"`
	Content   string `json:"content"`
}

MemoryRecord mirrors the brokered memory search result row.

func SearchMemory 

func SearchMemory(ctx context.Context, mcp MCPClient, executionID, namespace, query string, limit int) ([]MemoryRecord, error)

SearchMemory retrieves records from one namespace (empty namespace lets the grant decide).

type Models 

type Models struct {
	Fast      string
	Reader    string
	Reasoning string
}

Models binds the three logical capability tiers to concrete gateway model references for this deployment.

type Question 

type Question struct {
	ID            string   `json:"id"`
	Question      string   `json:"question"`
	Priority      int      `json:"priority"`
	SearchQueries []string `json:"searchQueries"`
}

Question is one planner decomposition unit (schema-aligned field names).

type ReaderErrorDisposition 

type ReaderErrorDisposition int
const (
	ReaderRetry ReaderErrorDisposition = iota
	ReaderSkip
	ReaderFail
)

type Runtime 

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

Runtime hosts the research roles behind the Fenced Runtime Interface. One process serves every agent version; the version reference selects the role so a single deployment can host the whole workflow fleet.

func NewRuntime 

func NewRuntime(mcpEndpoint string, models Models) *Runtime

NewRuntime builds the multi-role runtime.

func (*Runtime) Checkpoint 

func (r *Runtime) Checkpoint(_ context.Context, executionID string) (agent.Checkpoint, error)

Checkpoint implements agent.Runtime with versioned logical state.

func (*Runtime) Restore 

func (r *Runtime) Restore(_ context.Context, request agent.RestoreRequest) error

Restore implements agent.Runtime; restores are idempotent by contract.

func (*Runtime) Run 

func (r *Runtime) Run(ctx context.Context, request agent.StartRequest, emit agent.Emitter) (json.RawMessage, error)

Run implements agent.Runtime.

type SourceHit 

type SourceHit struct {
	SourceID           string `json:"sourceId"`
	Title              string `json:"title"`
	URL                string `json:"url"`
	Snippet            string `json:"snippet,omitempty"`
	Query              string `json:"query,omitempty"`
	ResearchQuestionID string `json:"researchQuestionId,omitempty"`
	QuestionText       string `json:"questionText,omitempty"`
}

SourceHit is one discovered source.

type SpawnOutcomeError 

type SpawnOutcomeError struct {
	Name    string
	Outcome string
	Message string
}

SpawnOutcomeError preserves the stable denial code so callers can treat idempotent name conflicts differently from policy or budget denials.

func (*SpawnOutcomeError) Error 

func (e *SpawnOutcomeError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
research-runtime serves the seven research workflow roles behind the Fenced Runtime Interface (HTTP).
 research-runtime serves the seven research workflow roles behind the Fenced Runtime Interface (HTTP).

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.