Advanced Agent Features

// Add an evaluation hook
agent.addEvalHook(myHook);

// Enable/disable evaluation
agent.setEvalEnabled(true);

// Record goal completion
agent.recordGoalCompletion("goal-1", true, Map.of("steps", 3));

// Set a planner
agent.setPlannerHandle(myPlanner);

// Plan for all goals
List<PlannerHandle.PlanStep> steps = agent.plan();

// Plan for a specific goal
List<PlannerHandle.PlanStep> steps = agent.planForGoal("deliverPackage");

// Execute a plan
PlannerHandle.PlanResult result = agent.executePlan(steps);

agent.setReasoningStrategy(reactStrategy);

// After chat, inspect reasoning
Optional<ReasoningResult> result = agent.getLastReasoningResult();

agent.setEnvironment(myEnvironment);

Percept percept = agent.perceive();
ActionOutcome outcome = agent.actOnEnvironment("moveForward", Map.of("speed", 5));

agent.setFeedbackCollector(myCollector);
FeedbackCollector collector = agent.getFeedbackCollector();

// Fan-out to multiple LLMs
ParallelLLM.ParallelResults results = agent.getEnsembleExecutor()
    .parallelChat("Explain quantum computing", List.of(gpt4, claude, gemini));

// Race: first response wins
Optional<ParallelLLM.LLMResult> fastest = agent.getEnsembleExecutor()
    .raceChat("Quick question", List.of(gpt4, claude), 10);

// Consensus with scoring
Optional<ParallelLLM.LLMResult> best = agent.getEnsembleExecutor()
    .consensusChat("Review this code", llms, response -> scoreQuality(response));

// Ensemble synthesis
Optional<String> synthesized = agent.getEnsembleExecutor()
    .ensembleChat("Complex analysis", List.of(gpt4, claude), aggregatorLLM);

Agent supervisor = new SupervisorAgent();
Agent developer = new DeveloperAgent();
Agent tester = new TesterAgent();

// Bidirectional parent-child links
supervisor.addChild(developer);
supervisor.addChild(tester);

// developer.getParent() == supervisor
// supervisor.getChildren() contains both

// Add multiple at once
supervisor.addChildren(developer, tester, designer);

// Supervisor delegates to child
supervisor.delegateToChild(developer.id(), "writeCode", Map.of(
    "task", "Implement authentication",
    "language", "Java"
));

// Developer escalates to supervisor
developer.escalateToParent("requestApproval", Map.of(
    "reason", "Production deployment requires sign-off"
));

public interface HierarchyContext {
    String getAgentId();
    Agent getAgentRef();
    Agent getParentRef();
    void setParentRef(Agent parent);
    List<Agent> getChildrenSnapshot();
    boolean hasChild(Agent child);
    boolean addChildDirect(Agent child);
    boolean removeChildDirect(Agent child);
    Agent findChildById(String childId);
    AgentCommunicationManager getCommunicationManager();
}

// Stream tokens as a Java Stream
Stream<String> tokens = agent.streamChat("Tell me about Java");
tokens.forEach(System.out::print);

agent.streamChatWithTools("Search for TnsAI docs", chunk -> {
    if (chunk.isContent()) {
        System.out.print(chunk.getContent());
    } else if (chunk.isToolCall()) {
        System.out.println("Tool: " + chunk.getToolCall().get().getName());
    }
});

// With direct event consumer
agent.chatWithEvents("Hello", event -> {
    if (event instanceof TextDeltaEvent delta) {
        System.out.print(delta.getText());
    } else if (event instanceof ToolCallStartEvent tc) {
        System.out.println("Calling: " + tc.getToolName());
    }
});

// With session-based publisher
agent.chatWithEvents("Hello", sessionId);

package com.example.tnsai.docs;

import com.tnsai.actions.model.ActionRequest;
import com.tnsai.agents.Agent;
import com.tnsai.cancellation.CancellationToken;
import com.tnsai.rag.ChatRetrievalContext;

import java.time.Duration;
import java.util.Map;

public final class ActionRetrievalContextExample {

    private ActionRetrievalContextExample() {}

    public static void dispatch(Agent agent) {
        CancellationToken cancellation = CancellationToken.create();
        ChatRetrievalContext context = ChatRetrievalContext.builder()
            .scope("tenant-a", "conversation-42")
            .runId("run-7")
            .simulationState("review")
            .currentEpisode("episode-3")
            .sourceRevision("kb-2026-08-12")
            .cancellationToken(cancellation)
            .timeout(Duration.ofSeconds(3))
            .metadataFilters(Map.of("tier", "approved"))
            .build();

        agent.streamChatWithTools("Summarize the evidence", chunk -> {}, context);
        agent.streamChatWithRetrievedContext(
            "Fenced outbound request", "Original user message", chunk -> {}, context
        );
        agent.chatWithEvents("Summarize the evidence", event -> {}, context);

        agent.executeAction(
            "answer", Map.of("question", "What changed?"), context
        );
        agent.executeAction(
            ActionRequest.of("answer", Map.of("question", "What changed?")),
            context
        );
        agent.executeActionOnRole(
            "researcher", "answer", Map.of("question", "What changed?"), context
        );
        agent.executeActionOnRole(
            "researcher",
            ActionRequest.of("answer", Map.of("question", "What changed?")),
            context
        );
    }
}

// Full control
Object response = chatOrchestrator.invokeLLM(message, useHistory, useTools, trace);

// Process response (handles text and tool calls)
String result = chatOrchestrator.processLLMResponse(response, useHistory);

// With custom parser
MyOutput output = agent.chatWithStructure(
    "Extract the key points",
    new MyOutputParser(),
    3  // maxRetries for correction
);

// With format detection (JSON, YAML, TOML)
MyRecord record = agent.chatWithFormat("Generate config", MyRecord.class, 2);

// With explicit format
MyRecord record = agent.chatWithFormat("Generate config", MyRecord.class, OutputFormat.YAML, 2);

agent.setVariant(AgentVariant.HIGH);
AgentVariant current = agent.getVariant();

// Auto-resolve based on task
AgentVariant resolved = agent.resolveVariant("Complex refactoring task");

// Custom selector
agent.setVariantSelector(mySelector);

agent.enableContextGraph(snapshotStore, decisionTraceStore);

Optional<ContextManagerHandle> cm = agent.getContextManager();
boolean enabled = agent.isContextGraphEnabled();

AgentHealthState health = agent.getHealthState();
ResilienceExecutor executor = agent.getResilienceExecutor();
RetryPolicy policy = agent.getDefaultRetryPolicy();
DeadLetterQueue dlq = agent.getDeadLetterQueue();
agent.clearRecoveryState();