Skip to main content

TruvaG3 Framework Features Guide

Overview​

TruvaG3 is a Kubernetes-native agent framework for building AI systems as ordinary services: tools expose focused capabilities, agents discover and orchestrate those capabilities, and the platform keeps discovery, execution, memory, observability, and resilience inside your own infrastructure.

This guide is a feature map for the framework. It is intentionally organized around what the framework provides rather than around implementation files. Use it when evaluating TruvaG3, planning a new agent system, or deciding which deeper guide to read next.

Table of Contents​

How To Read This Guide​

Start with Feature Map for the current framework surface. Each feature group links to the docs that go deeper.

For implementation details, prefer the module READMEs and architecture docs:

Feature Map​

1. Component Runtime​

TruvaG3 models an agent system as independently deployed components. The runtime distinction between tools and agents is central to the framework.

Tools​

Tools are passive components. They register capabilities, expose HTTP endpoints, and execute focused work when called. They can call external APIs, databases, internal services, or AI providers as part of their own implementation, but they do not discover or orchestrate other TruvaG3 components.

Typical tool features:

  • independent process and Kubernetes deployment
  • one or more registered capabilities
  • HTTP capability endpoints
  • health endpoint support
  • structured success/error responses
  • optional OpenAPI exposure

See Tool Development Guide and core/README.md.

Agents​

Agents are active components. They can register their own capabilities, discover tools and other agents, maintain request context, and coordinate complex work.

Typical agent features:

  • component registration and discovery
  • AI client integration
  • orchestration support
  • optional session, memory, and telemetry wiring
  • ability to expose capabilities other agents can call

See Agent Development Guide, Chat Agent Guide, and core/README.md.

Framework Lifecycle​

The core framework handles common runtime plumbing:

  • configuration loading from environment variables and functional options
  • HTTP server startup
  • component registration
  • health endpoints
  • CORS configuration
  • middleware wiring
  • graceful shutdown
  • logger propagation to framework modules

See API Reference and Environment Variables Guide.

Capability Registration​

Capabilities describe what a component can do. A registered capability gives the framework enough information to expose an endpoint, advertise the component in discovery, help LLMs choose tools, and optionally generate schemas and OpenAPI.

Capability metadata can include:

  • name
  • description
  • endpoint
  • input and output type hints
  • input summary
  • output summary
  • generated schema endpoint
  • internal flag
  • capability type

See Tool Development Guide.

Generated HTTP APIs​

Registered capabilities become HTTP-callable APIs. If a capability does not provide an explicit endpoint, the framework can generate one at /api/capabilities/{name}. Components also expose capability catalog endpoints that are useful for readiness checks, manual testing, and developer tooling.

Common generated or framework-managed endpoints include:

  • /health
  • /api/capabilities
  • /api/capabilities/{name}
  • /api/capabilities/{name}/schema when schema metadata is available
  • /openapi.json when OpenAPI generation is enabled

See core/README.md and Tool Development Guide.

CORS And Middleware​

The framework can wire HTTP middleware around component handlers. Built-in and documented patterns include CORS configuration, tracing middleware, and custom middleware for cross-cutting concerns.

This is useful when exposing agents or tools to browser clients, service meshes, gateways, or internal platform middleware.

See core/README.md, Tool Development Guide, and Distributed Tracing Guide.

2. Runtime Discovery​

Discovery lets agents find tools and other agents by what they can do rather than by hardcoded addresses.

Service Registry​

Redis/Valkey is the default service registry backend. The registry stores component records and capability indexes. The discovery interface is pluggable, so applications can replace the backend behind the core interfaces.

See Auto-Discovery Guide.

Capability Discovery​

Agents can discover components by:

  • capability
  • service name
  • component type
  • metadata filters
  • combined discovery filters

This supports dynamic orchestration: newly deployed tools become available to agents without redeploying those agents.

See Auto-Discovery Guide.

Heartbeat And TTL Leases​

Components register with TTL-backed leases and refresh those leases with heartbeats. If a component crashes or stops heartbeating, its registry entry expires automatically.

Discovery supports:

  • short-lived component identity leases
  • longer-lived capability indexes
  • automatic cleanup of dead components
  • multi-pod behavior where healthy replicas keep service-level capability indexes alive

See Auto-Discovery Guide.

Kubernetes Service-Fronted Discovery​

In Kubernetes, components can register stable service URLs instead of pod-local URLs. This lets agents call tools through Kubernetes Services and use native load balancing.

This model is compatible with transparent service meshes such as Istio and Linkerd. TruvaG3 still advertises the Kubernetes Service DNS name, while the mesh sidecars and mesh control plane can handle mTLS, traffic routing, policy, retries, and mesh telemetry. Mesh-specific routing should be configured in the mesh itself, such as with Istio VirtualService and DestinationRule resources or Gateway API HTTPRoute resources.

TruvaG3 does not currently provide first-class registration for custom mesh gateway hosts, custom VirtualService hosts, full advertised URLs, or path-prefixed gateway routes. That is intentional for now: the framework keeps discovery centered on Kubernetes Services and lets the platform own mesh-specific routing.

Relevant configuration includes:

  • TRUVAG3_K8S_SERVICE_NAME
  • TRUVAG3_K8S_SERVICE_PORT
  • TRUVAG3_K8S_NAMESPACE
  • TRUVAG3_K8S_POD_IP

See Auto-Discovery Guide §"Address Resolution" and Environment Variables Guide.

3. Tool Contracts And API Surfacing​

TruvaG3 treats tool contracts as runtime metadata, not a separate hand-maintained specification.

Capability Metadata​

Capability descriptions help both humans and LLM planners understand when a capability should be used. Good descriptions are the baseline for payload generation and tool selection.

See Tool Development Guide.

Input And Output Summaries​

InputSummary and OutputSummary provide structured field hints. They help LLMs generate correct JSON and help the framework generate schemas and OpenAPI.

See Tool Development Guide.

Three-Phase Payload Generation​

TruvaG3 uses progressive payload guidance:

  1. Description-based generation is always available.
  2. Field-hint-based generation is recommended.
  3. Schema-based validation is optional.

This lets simple tools stay simple while production tools can add stronger validation.

See Tool Schema Discovery Guide.

Schema Validation​

When enabled, the orchestrator can fetch capability JSON Schemas from tool endpoints, cache them, and validate LLM-generated payloads before sending tool calls.

See API Reference.

OpenAPI Generation​

When enabled, each component can expose /openapi.json, generated from registered capabilities. This supports Swagger UI, developer portals, API gateways, and human inspection.

The endpoint is disabled by default and can be enabled by configuration.

See Developer Tools Guide.

4. AI Provider Layer​

The AI module gives agents a provider-neutral interface for LLM calls.

Zero-Configuration Provider Detection​

ai.NewClient() can scan the environment, detect configured providers, and create a working client without hardcoding a provider in application code. This is useful for local development, promotion between environments, and running the same container image with different provider settings.

See ai/README.md and AI Providers Setup Guide.

Single Client​

The single client connects to one provider. It can auto-detect configured providers from environment variables or be configured explicitly.

See AI Providers Setup Guide.

Chain Client Failover​

The chain client tries multiple providers in order and fails over when errors are retryable. This supports high availability and provider outage handling.

See AI Providers Setup Guide.

Provider Aliases​

Provider aliases identify native providers, hosted request-aware profiles, and registered OpenAI-compatible services:

  • openai
  • anthropic
  • gemini
  • azureopenai.v1
  • azureopenai.classic
  • anthropic.vertex
  • bedrock
  • openai.groq
  • openai.deepseek
  • openai.xai
  • openai.mistral
  • openai.qwen
  • openai.together
  • openai.ollama

The Azure and Vertex profiles require explicit request-aware construction with application-owned routes and credentials and are not auto-detected. The native Bedrock provider is build-tagged and requires importing the Bedrock provider package and building with the bedrock tag.

See AI Providers Setup Guide.

Model Aliases​

Model aliases provide portable names, including default, fast, smart, premium, code, and vision, that resolve differently per provider. This lets application code request a model role without hardcoding provider-specific model IDs.

See AI Providers Setup Guide.

Provider Registry And Custom Providers​

The AI module has a provider registry. Providers register themselves through package initialization, and teams can add custom providers or OpenAI-compatible services behind the same AIClient interface. Optional factory contracts add error-capable validation and request-aware construction without breaking legacy factories.

This matters when evaluating the framework for private endpoints, internal gateways, new provider integrations, or self-hosted models.

Request-aware providers can reuse the shared request-policy engine. OpenAI-compatible enterprise adapters can also reuse the openaiwire codec without inheriting the stock OpenAI endpoint, credentials, retry, or telemetry behavior. SDK-native providers translate a provider-local logical draft instead; the build-tagged Bedrock adapter is the reference implementation.

See the Custom AI Providers and Enterprise Integration Guide, ai/README.md, and AI Architecture.

Request-Aware Policy And Enterprise Integration​

ai.NewRequestClient adds presence-aware portable parameters, sanitized request reports, provider patches, versioned middleware, and explicit refusal when a provider cannot represent an option. core.GenerateAI and core.StreamAI keep the dispatch contract in Core and fall back to legacy clients only when no semantics would be lost.

Enterprise integrations can supply concurrency-safe dynamic credentials, per-request endpoint resolution with stable non-secret route identities, and caller-owned HTTP clients. Credentials are attached at the transport boundary and excluded from reports, fingerprints, logs, and traces.

ai.NewChain builds heterogeneous failover chains from independently configured provider entries and injected clients. This supports different credentials, regional routes, or custom providers per entry while preserving the same provider-neutral orchestration API.

See the AI Providers Setup Guide, Custom AI Providers and Enterprise Integration Guide, and API Reference.

Embeddings And Vector Integration​

The AI layer includes embedding-capable interfaces for providers that support embeddings. The memory module can use an embedding client with Qdrant-backed shared knowledge and user memory.

This prevents agents from having to own vectorization code when adding semantic recall, shared knowledge search, or user memory.

See ai/README.md, memory/README.md, and API Reference.

Reasoning Controls And Request Options​

AI requests support common portable options such as temperature, max tokens, and system prompts. The request-aware API can separately express inherit, explicit set (including zero), and omit for temperature, top-p, top-k, max tokens, system prompt, reasoning effort, and response format. The documented provider setup also supports reasoning-model controls, request timeouts, token multipliers for reasoning models, and provider-specific escape hatches.

Orchestration can override AI options per phase, including planning, synthesis, micro-resolution, error analysis, tiered selection, and result distillation.

See AI Providers Setup Guide, AI Providers Setup Guide, AI Providers Setup Guide, and API Reference.

Streaming And AI Telemetry​

AI clients support non-streaming and streaming responses. When telemetry is initialized before the AI client, AI operations can emit spans and metrics such as provider, model, request duration, and token counts.

See ai/README.md and telemetry/README.md.

5. Orchestration​

The orchestration module coordinates tools and agents to satisfy user requests.

Dynamic Natural-Language Orchestration​

Dynamic mode lets users describe a request in natural language. The orchestrator asks an LLM to select tools, produce a plan, execute it, and synthesize the results.

Use this for chat interfaces, exploratory workflows, and systems where the needed tools vary by request.

See Orchestration Modes Guide.

DAG Execution​

Plans are modeled as directed acyclic graphs. Independent steps can run in parallel, while dependent steps wait for upstream results.

Features include:

  • dependency-aware execution
  • template references to prior step outputs
  • result aggregation
  • step-level callbacks
  • retry-aware execution

See orchestration/README.md.

Context Window And Token Budget Management​

The orchestration layer includes several mechanisms to avoid context-window overflow as the number of tools, conversation turns, and tool outputs grow:

  • tiered capability selection sends lightweight tool summaries first, then fetches full schemas only for selected tools
  • tiered selection is default for medium catalogs and is configurable through TRUVAG3_TIERED_RESOLUTION_ENABLED, TRUVAG3_TIERED_MIN_TOOLS, and TRUVAG3_TIERED_SELECTION_MAX_TOKENS
  • iterative planning can re-select tools in later phases using prior tools, continuation notes, and compact result summaries
  • continuation planning has a per-step result character limit so large delegated-agent responses do not swamp later planning prompts
  • orchestration responses expose token usage by phase, including planning, tiered_selection, synthesis, distillation, and retry phases

This is the planning-side context optimization layer. Large output handling is covered separately by Result Trimming And Distillation, and long chat sessions are covered by Conversation History Protection.

See orchestration/README.md, API Reference, and Limits Cheatsheet.

Iterative Multi-Phase Planning​

For complex requests, the planner can generate partial plans, execute a phase, feed results back into planning, and continue until the plan is terminal or configured limits are reached.

This supports research-style workflows where the first phase discovers context and later phases choose different tools based on what was found. Limits exist for maximum phases, total steps, phase timeout, and continuation prompt size.

See API Reference and Limits Cheatsheet.

Workflow Modes​

The framework supports multiple orchestration styles:

  • dynamic mode for LLM-generated plans
  • predefined workflow mode for deterministic pipelines
  • custom mode for exact step control and debugging
  • YAML workflow engine for declarative workflows

See Orchestration Modes Guide.

Streaming Orchestration​

Streaming orchestration emits progress and response events while work is running. This supports chat-style UX and long-running workflows where users need visibility before the final answer is complete.

See orchestration/README.md.

Clarification Requests​

When the planner needs user-provided information to proceed, the orchestrator can surface a structured clarification request. Simple chat UIs can forward the natural-language response, while richer UIs can render structured prompts from the Clarification field.

See orchestration/README.md and API Reference.

Execution Controls And Token Usage​

Orchestration exposes controls for production behavior and cost management:

  • max parallel step execution
  • per-step and total timeouts
  • plan parse retry
  • hallucinated agent retry
  • per-phase AI option overrides
  • step completion callbacks
  • aggregated token usage and token usage by orchestration phase

See API Reference, API Reference, and Limits Cheatsheet.

Prompt Customization​

Prompt customization supports:

  • PromptConfig
  • additional type rules
  • system instructions
  • domain-specific instructions
  • templates
  • custom prompt builders
  • iterative planning instructions

See LLM Planning Prompt Guide and Effective Prompts Guide.

Agent Skills​

Agent skills are reusable, versioned instruction packages that developers explicitly make available to an agent. They complement prompt configuration: the agent's identity and universal behavior stay in its system instructions, while conditional or reusable procedures can live in skills. Skills are disabled by default; an agent without an enabled, nonempty binding list follows the ordinary orchestration path without skill registry or selector calls.

For each skill-enabled request, orchestration follows a bounded five-stage lifecycle:

  1. resolve every binding and pin an exact immutable revision, including resolving a published alias at request start;
  2. activate eligible skills according to each binding's always, auto, or trusted explicit policy;
  3. select resources that apply to the current initial-planning, continuation, resume, or synthesis boundary;
  4. load and verify only the selected content; and
  5. project the admitted instructions into the prompt for that boundary.

This progressive loading keeps the full skill catalog out of every prompt. Continuation, resume, and synthesis boundaries re-evaluate resource relevance instead of carrying every previously loaded resource forward. Plan regeneration within the same phase reuses the already accepted projection exactly; it does not rerun activation or resource selection.

Application code injects the provider-neutral SkillRegistry interface. The included adapter supports Redis and Valkey, but agents do not depend directly on either product. Bindings belong to developer code or Kubernetes deployment configuration; an environment binding list replaces the complete code list so replicas remain consistent. Skills can suggest capability categories through tool hints, but they neither register nor authorize tools. Capability selection continues to use runtime discovery.

The management API validates and publishes packages. The shipped examples keep their source packages in Git, synchronize them automatically during setup, and provide strict skills-sync and skills-check maintenance commands. Registry Viewer supports package management and execution inspection, while Jaeger and structured logs expose the body-free runtime lifecycle.

See the Agent Skills Guide for the complete authoring, configuration, provider, deployment, observability, and operational workflow. See the Agent Development Guide for the minimum integration in a new agent.

Large Catalog Support​

For large systems, capability providers reduce prompt bloat and help the planner work with relevant subsets of a large tool/agent catalog.

See orchestration/README.md.

6. Reliability And Error Recovery​

TruvaG3 provides both generic resilience primitives and orchestration-specific recovery behavior.

Structured Tool Errors​

Tools communicate failures through structured error categories and retry hints. The shared protocol includes ToolError, ToolResponse, and upstream error classification helpers.

See Intelligent Error Handling Guide and Error Handling Guide.

LLM Error Analysis​

For input-like failures, the orchestrator can ask an LLM to inspect the error, original payload, capability metadata, and user request, then suggest corrected parameters.

See Error Handling Guide.

Semantic Retry​

Semantic retry performs contextual re-resolution when the original parameters were wrong or incomplete. This helps recover from failures such as ambiguous locations, invalid codes, or values that need to be derived from prior results.

See Error Handling Guide.

Result Trimming And Distillation​

Large tool and agent results can be processed before they are embedded in LLM prompts. This prevents token budget overflow during synthesis, continuation planning, micro-resolution, and downstream agent/tool calls.

Built-in controls include:

  • structural trimming enabled by default
  • per-result and total prompt byte budgets
  • micro-resolution source-data budget
  • downstream agent/tool input budget
  • content-aware field scoring and relevance-aware field selection
  • preservation of JSON structure, key names, and representative samples
  • preservation of large integer identifiers through the result-compaction and synthesis JSON round-trips (no float rounding)
  • honest loss disclosure — a deterministic content cut is flagged with content_lost and an inline note ([trimmed: …], [partial source: …]) that tells the model to treat omitted content as UNKNOWN, not absent
  • trim metadata on step results and result_trim.completed span events

For extremely large or domain-specific outputs, default-on result distillation (opt out with TRUVAG3_RESULT_DISTILL_ENABLED=false) adds a two-stage pipeline:

  1. structural pre-filtering reduces the source result
  2. an LLM summarizes the pre-filtered content to a target size (results above the model's usable context — or, when TRUVAG3_RESULT_DISTILL_MAPREDUCE_THRESHOLD is set, above that byte threshold — are chunked and map-reduced, so the whole result is analyzed rather than only the pre-filtered head)

The trimming contract is pluggable through the ResultProcessor interface, so teams can replace the default StructuralTrimmer with a domain-specific implementation.

See the Result Compaction Guide for the full walkthrough (trimming, distillation, map-reduce, and continuation digests), plus ResultTrimConfig / ResultDistillConfig in the API Reference, the Environment Variables Guide, and the Limits Cheatsheet.

Schema-Guided Mapping For Large Results​

When prior step results are too large for direct LLM parameter extraction, schema-guided mapping can use JSON schema analysis instead of sending raw result data into the micro-resolution prompt.

This is controlled by TRUVAG3_RESULT_TRIM_SCHEMA_MAPPING_THRESHOLD; setting it to 0 disables schema-guided mapping.

See API Reference and Environment Variables Guide.

Circuit Breakers​

Circuit breakers prevent cascading failures by failing fast after repeated errors, then testing recovery through half-open probes.

See resilience/README.md.

Retry And Backoff​

Retry logic supports exponential backoff, jitter, context cancellation, and maximum delay caps.

See resilience/README.md and Error Handling Guide.

Panic Recovery​

The resilience module includes panic recovery helpers so unexpected panics can be converted into errors, logged, and handled without tearing down the process.

See resilience/README.md.

7. Async Execution, HITL, And Scheduling​

Some agent workflows are too long-running or sensitive for a single synchronous request.

Async Tasks​

Async tasks implement the HTTP 202 plus polling pattern:

  1. API accepts the request and returns a task ID.
  2. Worker processes the task in the background.
  3. Client polls for status, progress, and final result.

See Async Orchestration Guide.

Progress Reporting​

Async task handlers can publish progress updates. Orchestration step callbacks can feed task progress so clients see meaningful state while execution runs.

See Async Orchestration Guide.

Human-in-the-Loop Approval​

HITL checkpoints pause execution until a human approves, rejects, aborts, or lets the checkpoint expire. The default command endpoint rejects unsupported edit, skip, retry, and respond commands before changing state.

Supported interrupt points include:

  • plan approval
  • before-step approval
  • error escalation

HITL supports Redis-backed checkpoint storage, webhook-style notifications, command handling, expiry processing, and framework-owned resume. Applications provide a processing adapter to ResumeCoordinator; the framework claims ownership, renews it during execution, and finalizes the actual outcome. Another interruption saves the parent as continued and exposes its successor.

See Human-in-the-Loop User Guide.

Scheduled Execution​

Scheduled execution lets agents schedule future work:

  • one-shot delay
  • absolute time
  • recurring cron

The scheduler tool creates schedules, the scheduled executor dispatches due work, and target agents receive scheduled instructions through a registered endpoint.

See Scheduled Tasks Guide.

Pluggable Task Backends​

Async tasks and scheduled execution use related but distinct backend interfaces:

  • async worker flow: TaskQueue and TaskStore
  • scheduled producer and consumer flow: ScheduleStore, TaskDispatcher, TaskConsumer, and TaskHandle

Redis list-backed implementations cover the default async path and the default scheduled consumer. Redis Streams supports at-least-once scheduled task consumption, and in-memory implementations support development and tests. Conformance tests help validate custom TaskConsumer implementations.

See Scheduled Tasks Guide.

8. Memory And Context​

Memory and context features let agents avoid starting from zero on every request.

Component Key-Value Memory​

The core module defines a simple component memory interface with Get, Set, Delete, and Exists. Components can use this for small state, cached values, and local context. In-memory storage supports development and tests, while Redis-backed memory is the production path for distributed instances.

This is separate from shared agent memory and user memory: it is the lightweight per-component storage primitive.

See core/README.md and API Reference.

Pipeline Hooks​

Pipeline hooks run at defined stages:

  • before planning
  • after planning
  • after execution
  • after synthesis

Hooks can inject context, short-circuit the pipeline, mutate plans, observe results, or post-process responses. Ordinary hook callback errors use the stage's fail-open fallback. A RequiredAfterPlanningHook instead stops the phase if its plan governance fails, before HITL or execution. Invalid explicit BeforePlanning decisions also stop the request. Panics propagate rather than using the ordinary error fallback, even for optional hooks.

See Adding Context To Your Agent and the Pipeline Hooks Guide.

Shared Agent Memory​

Shared memory gives agents in the same domain visibility into recent work and learned knowledge.

Features include:

  • episodic event recording
  • investigation coordination
  • real-time activity coordination
  • digest caching
  • vector-backed shared knowledge
  • LLM-powered memory reflection

See memory/README.md and Agent Memory User Guide.

Per-User Memory​

Per-user memory supports personalization for assistant-like agents. It can extract user facts from conversations, reconcile them against existing facts, and recall relevant facts later through semantic search.

Features include:

  • user-scoped facts
  • ADD/UPDATE/CONTRADICT/DUPLICATE reconciliation
  • semantic recall
  • GDPR-style forget support

See Agent Memory User Guide.

Conversation History Protection​

Conversation history preparation gives chat agents multi-turn context while protecting prompt budgets.

Features include:

  • raw turn metadata
  • prompt-safe conversation history enrichment
  • Tier 1 token budgeting
  • Tier 2 recursive compaction for long sessions
  • reuse across planning, continuation, and synthesis prompts

See Conversation History Guide.

RAG, Caching, And Guardrails​

Pipeline hooks can implement:

  • RAG context injection
  • semantic caching
  • response filtering
  • PII redaction
  • analytics logging
  • custom context enrichment

See Adding Context To Your Agent.

9. Chat Agent Features​

The chat guides describe a reference pattern for production chat agents built on top of orchestration.

SSE Streaming​

Server-Sent Events can stream status, step progress, token chunks, errors, and completion events to the frontend.

See Chat Agent Guide.

Session Storage​

Example chat agents use Redis-backed session storage. Sessions store metadata and bounded message history with TTL.

See Chat Session Management Guide.

Multi-Turn Context​

Chat handlers convert stored messages into conversation turns and pass them into orchestration metadata. The orchestration layer prepares the prompt-safe conversation history.

See Conversation History Guide.

HITL Resume For Chat​

The DevOps chat example carries session context through HITL interruptions so an approval resume can continue the same conversation when the session is still available.

See Chat Session Management Guide.

10. Observability And Developer Tools​

TruvaG3 is built around OpenTelemetry-compatible observability and developer-facing runtime inspection.

OpenTelemetry Metrics​

Telemetry supports counters, histograms, and gauges, plus unified helper functions for common framework metrics.

Features include:

  • request metrics
  • tool call metrics
  • AI request metrics
  • token metrics
  • error metrics
  • service type labels
  • cardinality protection
  • graceful degradation if telemetry backends fail

See telemetry/README.md and API Reference.

Distributed Tracing​

Tracing uses W3C TraceContext propagation. The telemetry module provides server middleware and traced HTTP clients.

Features include:

  • incoming trace extraction
  • span creation
  • outgoing trace injection
  • trace-log correlation
  • request filtering
  • custom span names
  • AI spans
  • async boundary linking
  • HITL cross-trace correlation

See Distributed Tracing Guide.

Structured Logging​

The framework provides a logger interface with basic and context-aware methods. Context-aware logging carries trace IDs when request context is available.

See Logging Implementation Guide.

LLM And Execution Debug Stores​

Debug stores can persist full LLM payloads and execution records with base TTLs for troubleshooting orchestration behavior. HITL, related-lineage, and explicit investigation retention may extend those minimums. The telemetry package also includes LLM call recording interfaces for storing request/response metadata outside the request path.

See Environment Variables Guide, API Reference: LLM Debug Store, and API Reference: LLM Call Recording.

Registry Viewer​

The Registry Viewer is a developer-facing runtime dashboard. It can inspect:

  • service registry
  • LLM debug records
  • HITL checkpoints
  • conversation-grouped execution lineage and interactive DAGs
  • raw synthesis evidence versus stored post-AfterSynthesis application responses
  • provider-neutral pipeline-hook outcomes stored with each execution
  • optional request-level Jaeger trace links for navigation only
  • skill package management and version history
  • per-execution skill pinning, activation, resource loading, and prompt projection evidence
  • shared memory

See Developer Tools Guide.

Swagger UI​

Swagger UI consumes generated OpenAPI specs from components that expose /openapi.json. It supports interactive API exploration and can integrate with developer portals and API gateways.

See Developer Tools Guide.

11. Security And Request Propagation​

Security features focus on propagating authentication and request metadata through orchestrated calls, keeping sensitive configuration out of code, and aligning agent systems with normal Kubernetes and service-platform controls.

Security Model​

TruvaG3 components are ordinary HTTP services. The framework does not replace your API gateway, identity provider, service mesh, Kubernetes RBAC, network policies, mTLS, or secrets management. Instead, it provides the hooks and propagation points needed to fit into those systems.

This means the framework helps with:

  • forwarding user or service tokens to downstream tools
  • propagating tenant, audit, and correlation metadata
  • preventing propagated headers from overriding framework-reserved headers
  • keeping API keys and provider credentials in environment-backed secrets
  • exposing runtime metadata only when explicitly enabled
  • adding guardrails, redaction, and audit behavior through hooks and prompt builders

See README.md and the OAuth Security Guide.

OAuth Bearer Propagation​

The orchestrator can attach Bearer tokens to outbound tool and agent calls through:

  • static configuration
  • runtime token setters
  • per-request context injection

See OAuth Security Guide.

Runtime Token Refresh​

OAuth tokens and propagated headers can be updated at runtime. This supports service-to-service token refresh without rebuilding the orchestrator or stopping in-flight requests.

See OAuth Security Guide.

Custom Header Propagation​

Custom headers support multi-tenant routing, audit metadata, and correlation IDs. Context-level headers override config-level defaults, while protected framework headers cannot be overridden by propagated headers.

See OAuth Security Guide.

Protected Framework Headers​

The executor reserves framework-critical headers such as Content-Type, Authorization, X-TruvaG3-Request-ID, and X-TruvaG3-Step-ID. Propagated headers cannot override these reserved values, which prevents accidental breakage of authentication, content handling, or trace/request correlation.

See OAuth Security Guide.

OpenAPI And Developer Tool Exposure​

OpenAPI generation is disabled by default because it exposes component API surface. Schema endpoints are generated when schema metadata is available. Teams should treat /openapi.json, schema endpoints, Swagger UI, and the Registry Viewer as developer/operator tooling and protect them at the network, gateway, or mesh layer.

Developer tooling has additional privacy boundaries: the Registry Viewer intentionally does not expose per-user memory contents in its shared-memory views.

See Developer Tools Guide and Developer Tools Guide.

Privacy, Guardrails, And Audit Hooks​

Pipeline hooks and custom prompt builders provide extension points for application-specific controls:

  • PII redaction before returning responses
  • content policy checks
  • tenant-aware prompt construction
  • audit logging for prompts and LLM calls
  • domain-specific compliance instructions
  • filtering or enriching context before planning

For streaming responses, note that AfterSynthesis hooks run after tokens have already streamed; use pre-planning hooks, guarded prompt builders, or non-streaming paths when content must be blocked before user delivery.

See Adding Context To Your Agent, LLM Planning Prompt Guide, and Developer Tools Guide.

Kubernetes Secrets And Config​

API keys, OAuth tokens, and provider keys should be managed through Kubernetes Secrets. Non-sensitive deployment settings can be managed through ConfigMaps.

See Environment Variables Guide and AI Providers Setup Guide.

Platform Security Controls​

Typical Kubernetes platform controls expected around TruvaG3 deployments:

  • Kubernetes Secrets for AI provider keys and service credentials
  • ConfigMaps for non-sensitive runtime configuration
  • non-root containers and pod security contexts
  • NetworkPolicies for service-to-service restrictions
  • ServiceAccounts and RBAC with minimal permissions
  • ingress, gateway, service mesh, or mTLS controls at trust boundaries

See the AI Providers Setup Guide.

12. Deployment And Operations​

TruvaG3 is designed to run inside existing platform infrastructure.

Kubernetes-Native Deployment​

The framework aligns with ordinary Kubernetes primitives:

  • Deployments
  • Services
  • Ingress
  • ConfigMaps
  • Secrets
  • health probes
  • namespace isolation
  • rolling updates

Environment Configuration​

The framework can be configured through environment variables and functional options. The environment guide marks variables by implementation status and groups them by subsystem.

See Environment Variables Guide.

Self-Hosted Operation​

TruvaG3 is intended for teams that want agents, tools, discovery, traces, and runtime data inside their own environment. This supports restricted, regulated, and air-gapped-friendly deployments.

See README.md.

Runtime Backends​

Common runtime backends include:

  • Redis/Valkey for discovery, sessions, memory events, scheduling, async tasks, Redis Streams consumers, debug stores, and the included skills package store (shared DB 0 with versioned deployment keyspaces in standalone, Sentinel, and cluster modes)
  • Qdrant for vector-backed shared knowledge and user memory
  • OpenTelemetry Collector for metrics and traces
  • Prometheus, Jaeger, Grafana, and Loki in the example stack

See Environment Variables Guide and memory/README.md.

13. Extension Points​

TruvaG3 exposes interfaces at the boundaries where teams are likely to need replacement or customization.

Pluggable Interfaces​

Examples include:

  • discovery and registry interfaces
  • AI client interface
  • telemetry interface
  • memory interfaces
  • task queue and task store interfaces for async work
  • schedule store, scheduler dispatcher, task consumer, and task handle interfaces
  • LLM debug, execution debug, and LLM call recording store interfaces
  • embedding client interface

See API Reference.

Custom Hooks​

Pipeline hooks are the main extension point for context engineering, caching, memory, guardrails, auditing, and background side effects.

See Adding Context To Your Agent.

Custom Prompt Builders​

Prompt builders allow teams to replace prompt construction logic while preserving the orchestration interfaces.

See LLM Planning Prompt Guide.

Testing And Conformance Helpers​

The framework includes test-friendly implementations and contracts so developers can add features without standing up the full runtime:

  • in-memory discovery for tests
  • in-memory task consumers and stores for dev/test flows
  • NoOp implementations for optional memory, HITL, and hook dependencies
  • mock memory and discovery implementations
  • core/conformance tests for custom TaskConsumer backends

See core/README.md, Scheduled Tasks Guide, and API Reference.

MCP Integration Paths​

TruvaG3 tools and MCP servers solve different problems. The documented direction is to add MCP at the edges:

  • expose TruvaG3 tools to MCP clients through an MCP gateway
  • consume external MCP servers as virtual TruvaG3 tools

See TruvaG3 Tools vs MCP Servers.

Feature-To-Module Index​

Feature AreaPrimary ModuleSupporting Modules
Tools, agents, generated HTTP APIs, framework runtimecoretelemetry
Discovery and registrationcoreRedis/Valkey backend
AI provider clients, provider registry, embeddingsaitelemetry, memory
Dynamic planning, iterative planning, and workflow executionorchestrationcore, ai, telemetry
Reusable agent skills and progressive prompt disclosureorchestrationProvider-neutral skill backend, core, telemetry
Async tasks and scheduling interfacescore, orchestrationRedis/Valkey backend
HITL approvalsorchestrationRedis/Valkey backend
Component, shared, and user memorycore, memoryorchestration, telemetry, Redis/Valkey, Qdrant
Resilience primitivesresiliencecore, telemetry
Metrics, tracing, logging supporttelemetrycore
OpenAPI generationcorecapability metadata
Test helpers and backend conformancecoreorchestration, memory

Documentation Index​

Use these docs for deeper feature-level details: