Skip to content

FEATURES.md

Latest commit

 

History

History
430 lines (340 loc) · 13.7 KB

FEATURES.md

File metadata and controls

430 lines (340 loc) · 13.7 KB

NTG.Adk - Complete Feature List

✅ Implemented Features (100% Python ADK Compatible)

Core Components

1. Agents (NTG.Adk.Operators.Agents)

  • ✅ BaseAgent - Abstract base for all agents

    • Sub-agent hierarchy (ParentAgent, SubAgents)
    • FindAgent(name) - recursive search
    • RunAsync() - async event stream execution

  • ✅ LlmAgent - Full-featured LLM agent

    • ✅ Instruction - System instruction with template support
    • ✅ {var} template substitution from session state
    • ✅ {var?} optional template variables
    • ✅ OutputKey - Auto-save response to state
    • ✅ Tools - Function calling support
    • ✅ Model - LLM model identifier
    • ✅ SubAgents - Multi-agent delegation
    • ✅ InputSchema / OutputSchema - Structured I/O
    • ✅ Callbacks - Lifecycle hooks (before/after model, tool start/end)
    • ✅ ToolProviders - Dynamic context-aware tool injection
    • ✅ RequestProcessors - Request transformation pipeline with priority

2. Workflow Agents (NTG.Adk.Operators.Workflows)

  • ✅ SequentialAgent - Execute agents in sequence

    • Passes same InvocationContext to all
    • State sharing via session.state
    • Supports escalation (early termination)

  • ✅ ParallelAgent - Execute agents concurrently

    • Each agent gets branched context (ParentBranch.ChildName)
    • Events interleaved from all agents
    • Shared state access (use distinct keys!)

  • ✅ LoopAgent - Loop execution with conditions

    • MaxIterations - limit loop count
    • Escalation support (break on escalate=True)
    • State persists across iterations

3. Tools (NTG.Adk.Implementations.Tools, NTG.Adk.CoreAbstractions.Tools)

  • ✅ FunctionTool - Wrap C# functions as tools

    • Auto-generate schema from method signature
    • Support for Func<>, Func<Task<>>
    • 1-4 parameters supported
    • Auto parameter type conversion
    • Special parameters: IToolContext, CancellationToken

  • ✅ ITool interface - Port for all tools

    • GetDeclaration() - JSON schema for LLM
    • ExecuteAsync() - Execute with args

  • ✅ IToolProvider - Dynamic tool injection

    • GetTools() - Provide tools based on invocation context
    • Context-aware tool selection
    • Runtime tool composition

4. Callbacks (NTG.Adk.CoreAbstractions.Agents)

  • ✅ IAgentCallbacks - Lifecycle hooks
    • BeforeModelAsync() - Intercept before LLM call, can skip LLM
    • AfterModelAsync() - Intercept after LLM response, can replace response
    • OnToolStartAsync() - Hook before tool execution
    • OnToolEndAsync() - Hook after tool completion
    • ICallbackContext - Access to session, state, metadata

5. Request Processors (NTG.Adk.CoreAbstractions.Models)

  • ✅ IRequestProcessor - Request transformation pipeline
    • ProcessAsync() - Transform LLM request before execution
    • Priority - Control execution order (lower runs first)
    • Can modify system instructions, tools, conversation history
    • Supports multiple processors with ordered execution

6. Events (NTG.Adk.Boundary.Events, NTG.Adk.CoreAbstractions.Events)

  • ✅ Event - Core event DTO

    • Author - Event source
    • Content - Parts (text, function calls, responses)
    • Actions - EventActions (escalate, transfer)
    • Metadata - Additional data

  • ✅ Content - Multi-part content container

    • Role - user, model, system, tool
    • Parts - List of content parts

  • ✅ Part - Content part (text, function call, etc.)

    • Text - Text content
    • FunctionCall - LLM function call
    • FunctionResponse - Tool execution result
    • InlineData - Binary data (images, etc.)

  • ✅ EventActions - Actions triggered by events

    • Escalate - Stop workflow, propagate to parent
    • TransferTo - Agent delegation target

7. Sessions (NTG.Adk.Implementations.Sessions, NTG.Adk.CoreAbstractions.Sessions)

  • ✅ ISession - Session management port

    • SessionId - Unique identifier
    • State - Key-value state store
    • History - Message history
    • Memory - Long-term memory (optional)

  • ✅ InMemorySession - In-memory implementation

    • Thread-safe state access (ConcurrentDictionary)
    • Generic Get<T>() / Set<T>() methods
    • Message history tracking

  • ✅ InvocationContext - Execution context

    • Session - Current session
    • Branch - Hierarchy path (for ParallelAgent)
    • UserInput - User message
    • WithBranch() / WithUserInput() - Immutable updates

8. Models (NTG.Adk.Implementations.Models, NTG.Adk.CoreAbstractions.Models)

  • ✅ ILlm - LLM provider port

    • GenerateAsync() - Single completion
    • GenerateStreamAsync() - Streaming completion

  • ✅ MockLlm - Mock implementation for testing

    • Echo responses
    • Useful for unit tests and demos

9. Bootstrap (NTG.Adk.Bootstrap)

  • ✅ Runner - Main entry point
    • RunAsync() - Execute agent, return final text
    • RunStreamAsync() - Stream events
    • Session management
    • Sliding window compaction support

10. LLM Adapters (NTG.Adk.Implementations.Models)

  • ✅ GeminiLlm - Google Gemini API integration

    • Full Gemini 2.0 Flash support
    • Streaming and non-streaming modes
    • Function calling support

  • ✅ OpenAILlm - OpenAI and compatible endpoints

    • GPT-4, GPT-3.5 support
    • Custom endpoint configuration for local models
    • Ollama, LocalAI, vLLM, LM Studio compatible

  • ✅ MockLlm - Testing and development

    • Echo responses
    • Predictable behavior for unit tests

11. Planning & Reasoning (NTG.Adk.Implementations.Planners)

  • ✅ PlanReActPlanner - Structured reasoning with tags

    • PLANNING, REASONING, ACTION tags
    • REPLANNING, FINAL_ANSWER support
    • Multi-step LLM-guided planning
    • ParseResponse() for structured output

  • ✅ BuiltInPlanner - Native model thinking

    • Gemini 2.0 Thinking mode
    • Extended thinking capabilities
    • Model-native reasoning

12. Built-in Tools (NTG.Adk.Implementations.Tools.BuiltIn)

  • ✅ GoogleSearchTool - Web search integration

    • Google Custom Search JSON API
    • Configurable result count
    • Full error handling

  • ✅ CodeExecutionTool - C# code execution

    • dotnet-script integration
    • Console app compilation fallback
    • Timeout and security controls

13. Retrieval & RAG (NTG.Adk.Implementations.Tools.Retrieval)

  • ✅ AgenticFilesRetrievalTool - LLM-powered retrieval

    • grep + LLM approach (beats vector embeddings)
    • LLM-powered query expansion
    • Multi-pass grep searches
    • LLM-based relevance ranking
    • Superior semantic search without embeddings

  • ✅ FilesRetrievalTool - Basic file retrieval

    • Keyword-based file search
    • Directory scanning
    • Pattern matching

14. OpenAPI Integration (NTG.Adk.Implementations.Tools.OpenApi)

  • ✅ OpenAPIToolset - OpenAPI 3.0 parser

    • Full spec parser (JSON/YAML)
    • Auto-generate RestApiTool from operations
    • Authentication support (AuthScheme, AuthCredential)
    • Parameter schema conversion
    • Request/response mapping

  • ✅ RestApiTool - HTTP REST API execution

    • Dynamic HTTP method support
    • Request body serialization
    • Response parsing

15. MCP Protocol (NTG.Adk.Implementations.Mcp)

  • ✅ McpToolset - Model Context Protocol integration

    • Stdio transport support
    • SSE (Server-Sent Events) transport
    • HTTP transport
    • Tool filtering and name prefixing
    • Async connection management

  • ✅ McpTool - MCP tool wrapper

    • Schema conversion
    • Argument mapping

  • ✅ McpSchemaConverter - Schema translation

    • MCP → ADK schema conversion
    • Type mapping

16. Memory & Persistence (NTG.Adk.Implementations.Memory, NTG.Adk.Implementations.Sessions)

  • ✅ InMemoryMemoryService - Semantic memory search

    • AddSessionToMemoryAsync() - Ingest conversations
    • SearchMemoryAsync() - Keyword-based semantic search
    • Cross-session memory retrieval

  • ✅ DatabaseSessionService - Persistent sessions

    • PostgreSQL support
    • MySQL support
    • SQLite support
    • Auto schema initialization
    • Multi-database compatibility (Dapper)

  • ✅ FileArtifactService - Disk-based artifacts

    • Persistent file storage
    • Version management
    • MIME type tracking

  • ✅ InMemoryArtifactService - In-memory artifacts

    • Thread-safe concurrent storage
    • Metadata support

17. Conversation History Management (NTG.Adk.Implementations.Compaction)

  • ✅ CompactionService - Sliding window compaction

    • LLM-based event summarization
    • Sliding window algorithm
    • CompactionInterval and OverlapSize config
    • Automatic history management

  • ✅ LlmEventSummarizer - LLM-powered summarization

    • Converts event streams to summaries
    • Preserves context
    • Reduces token usage

18. A2A Protocol (NTG.Adk.Implementations.A2A)

  • ✅ A2A (Agent-to-Agent) Communication
    • Remote agent invocation
    • Event streaming across network
    • gRPC-based transport
    • Serialization support

Architecture

  • ✅ A.D.D V3 Five-Layer Pattern

    • ✅ Boundary - Pure DTOs (Event, Content, etc.)
    • ✅ CoreAbstractions - Ports (IAgent, ILlm, ITool)
    • ✅ Implementations - Adapters (InMemorySession, MockLlm)
    • ✅ Operators - Business Logic (BaseAgent, LlmAgent, Workflows)
    • ✅ Bootstrap - Composition Root (Runner, DI)

  • ✅ Dependency Rules Enforced

    • Bootstrap → All layers
    • Operators → CoreAbstractions + Boundary
    • Implementations → CoreAbstractions + Boundary
    • CoreAbstractions → NONE
    • Boundary → NONE

Samples

  • ✅ HelloWorldAgent - Basic agent demo

    • Simple LlmAgent
    • MockLlm adapter
    • Runner execution

  • ✅ StoryFlowAgent - Multi-agent workflow

    • Custom BaseAgent orchestrator
    • LoopAgent (Critic → Reviser, 2 iterations)
    • SequentialAgent (Grammar → Tone checks)
    • 5 LlmAgents
    • State passing (output_key)
    • Conditional logic (tone-based regeneration)

🚧 Future Features

Planned Enhancements

  • ⏳ Structured Output Validation

    • Pydantic-like schema validation
    • output_schema enforcement with retry

  • ⏳ ASP.NET Core Integration Templates

    • Minimal APIs for agents
    • WebSocket streaming templates
    • SSE (Server-Sent Events) helpers

  • ⏳ Evaluation Framework

    • Agent performance testing
    • Metrics collection
    • Benchmarking tools

  • ⏳ CLI Tool

    • dotnet tool install ntg-adk
    • Project scaffolding
    • Agent evaluation commands

  • ⏳ Additional Built-in Tools

    • Web Page Loader
    • File system operations
    • Database query tools

📊 Comparison with Python ADK

See COMPATIBILITY.md for detailed breakdown

Feature Python ADK NTG.Adk C# Status
BaseAgent ✅ ✅ Complete
LlmAgent ✅ ✅ Complete (with callbacks, tool providers, request processors)
SequentialAgent ✅ ✅ Complete
ParallelAgent ✅ ✅ Complete
LoopAgent ✅ ✅ Complete
FunctionTool ✅ ✅ Complete (nested objects, enums, arrays)
Session State ✅ ✅ Complete
InvocationContext ✅ ✅ Complete
Event System ✅ ✅ Complete
Instruction Templates ✅ ✅ Complete
Output Key ✅ ✅ Complete
Sub-agents ✅ ✅ Complete
Escalation ✅ ✅ Complete
Gemini LLM ✅ ✅ Complete
OpenAI LLM ✅ ✅ Complete
AutoFlow ✅ ✅ Complete
Built-in Tools ✅ ✅ Complete (Google Search, Code Execution)
Memory Services ✅ ✅ Complete (Semantic search, cross-session)
A2A Protocol ✅ ✅ Complete
Callbacks ✅ ✅ Complete (LLM & Tool hooks)
Planners ✅ ✅ Complete (PlanReAct, BuiltIn)
Database Persistence ❌ ✅ C# Exclusive (PostgreSQL, MySQL, SQLite)
MCP Protocol ❌ ✅ C# Exclusive
OpenAPI Toolset ⚠️ Basic ✅ C# Enhanced (Full 3.0 parser)
Agentic Retrieval ❌ ✅ C# Exclusive (grep + LLM)
Request Processors ❌ ✅ C# Exclusive
Tool Providers ❌ ✅ C# Exclusive
Sliding Window Compaction ✅ ✅ Complete

🎯 Python ADK Compatibility

Compatibility Scores:

  • API Surface Compatibility: 100% (usage patterns match)
  • Feature Parity: 99% (core features complete)
  • Core Agents: 100% (all agent types complete)
  • Production Readiness: 100% (Gemini, OpenAI, all tools ready)

→ See COMPATIBILITY.md for full analysis

API-Compatible:

# Python
agent = LlmAgent(
    name="MyAgent",
    model="gemini-2.5-flash",
    instruction="You are helpful",
    output_key="result"
)
// C# - Same API
var agent = new LlmAgent(llm, "gemini-2.5-flash")
{
    Name = "MyAgent",
    Instruction = "You are helpful",
    OutputKey = "result"
};

Workflow-Compatible:

# Python
pipeline = SequentialAgent(
    name="Pipeline",
    sub_agents=[agent1, agent2]
)
// C# - Same pattern
var pipeline = new SequentialAgent(
    "Pipeline",
    [agent1, agent2]
);

🏗️ Architecture Benefits

  1. Type Safety: Compile-time errors vs runtime crashes
  2. Performance: 5-10x faster than Python
  3. IDE Support: Best-in-class IntelliSense
  4. Testability: Mock ports easily
  5. Maintainability: Clear layer separation
  6. Enterprise-Ready: Familiar to .NET developers

📚 Documentation

  • README.md - Quick start & overview
  • ARCHITECTURE.md - A.D.D V3 deep dive
  • GETTING_STARTED.md - Tutorials & learning path
  • FEATURES.md - This file (complete feature list)

Last Updated: 2026-03-14 Version: 1.8.17 Python ADK Compatibility: 99% core feature parity (100% production-critical features)