agentic-ai-sdk 1.0.0

SDK for building AI agent 2.0.

Agentic AI SDK

A production-ready SDK for building AI agents with planning, workspace management, artifact persistence, and observability. Built on top of Microsoft Agent Framework.

Overview

Agentic AI SDK supports three development modes:

Mode	Use Case	Requirements
Declarative Assembly	Assemble existing Tools via YAML (no code)	Docker or Python + SDK
Tool Development	Extend with new Python tools	Python 3.10+
Pro-Code Agent	Full programmatic control	Python + SDK APIs

Installation

# Basic installation
pip install agentic-ai-sdk

# With AG-UI protocol support (for web UI integration)
pip install agentic-ai-sdk[ag-ui]

# With observability (OpenTelemetry)
pip install agentic-ai-sdk[observability]

# All features
pip install agentic-ai-sdk[all]

Quick Start

Option 1: Docker Launch (Recommended, Zero Dependencies)

# Start Agent service with a single command
docker run -p 8000:8000 \
  -v $(pwd)/env.yaml:/app/env.yaml \
  -v $(pwd)/manifest:/app/manifest \
  agentic-analyst:latest

# Start frontend Web UI
docker run -p 3000:3000 \
  -e AGENT_BACKEND_URL=http://host.docker.internal:8000/ \
  agentic-ai-web-default:latest

# Access: http://localhost:3000/agentic-ai

Option 2: CLI Launch (For Developers)

# Interactive terminal mode
agentic-ai run --agent my_agent --config env.yaml

# AG-UI server mode (for frontend integration)
agentic-ai serve --port 8000

Option 3: Programmatic Usage

from agentic_ai import (
    build_agent,
    create_workspace,
    create_llm_factory_from_list,
)
from agent_framework import AIFunction

# Define tools
@AIFunction
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"The weather in {city} is sunny, 22°C."

# Create LLM factory
llm_factory = create_llm_factory_from_list([{
    "name": "default",
    "provider": "azure_openai",
    "model": "gpt-4o",
    "endpoint": "https://your-endpoint.openai.azure.com",
    "api_key_env": "AZURE_OPENAI_API_KEY",
}])

# Build agent
workspace = create_workspace(".ws/my_agent")
session = build_agent(
    chat_client=llm_factory.get_client("default"),
    workspace=workspace,
    agent_id="my_agent",
    tools=[get_weather],
    instructions="You are a helpful assistant.",
    planning_enabled=True,
)

# Run agent
response = await session.run("What's the weather in Beijing?")
print(response.text)

Project Structure

my-agent-project/
├── env.yaml                    # Environment config (LLM, connections)
├── manifest/
│   ├── agents.yaml             # Agent configuration
│   ├── tools.yaml              # Tool configuration
│   └── prompts/
│       └── my_agent.md         # System prompt
└── toolsets/                   # Tool implementations
    └── my_tools/
        └── tools.py

Declarative Configuration

Agent Configuration (agents.yaml)

version: "1.0"

agents:
  my_agent:
    llm_profile_name: "default"
    name: "My Agent"
    description: "A helpful assistant"
    max_tool_iterations: 30
    planning_enabled: true
    system_prompt_file: "manifest/prompts/my_agent.md"
    
    context_compaction:
      enabled: true
      max_messages: 80
      max_tokens: 180000
    
    tools:
      - my_tool
      - another_tool
    
    subagents:
      - sub_agent_1

Tool Configuration (tools.yaml)

version: "1.0"

defaults:
  output_policy: managed
  preview_rows: 200

tools:
  my_tool:
    function: "toolsets.my_tools.tools:my_tool"
    description: "My custom tool"
    config:
      timeout: 30
      max_results: 100

Environment Configuration (env.yaml)

llm_profiles:
  - name: default
    provider: azure_openai
    model: gpt-4o
    endpoint: ${AZURE_OPENAI_ENDPOINT}
    api_key: ${AZURE_OPENAI_API_KEY}

logging:
  level: INFO

observability:
  enabled: true
  service_name: "my-agent"

Tool Development

Creating Tools

from agent_framework import ai_function
from agentic_ai.artifacts import ToolResult, ok, error, persist
from agentic_ai.runtime import tool_handler

@ai_function(name="my_tool")
@tool_handler()  # Auto exception handling
async def my_tool(query: str) -> ToolResult:
    """My custom tool."""
    data = await fetch_data(query)
    return ok(data)

# For large data, use artifact persistence
@ai_function(name="generate_report")
@tool_handler()
async def generate_report(query: str) -> ToolResult:
    """Generate report with artifact persistence."""
    full_data = await fetch_large_dataset(query)
    preview = full_data[:50]
    
    return persist(
        data=full_data,           # Full data stored in artifact
        tool_return=preview,      # Preview returned to LLM
        summary={"total_rows": len(full_data)},
    )

Configuration Injection

from agentic_ai.runtime import get_effective_tool_config, get_client

@ai_function(name="search_data")
@tool_handler()
async def search_data(query: str) -> ToolResult:
    """Search with injected config."""
    # Get merged config from env.yaml + tools.yaml
    config = get_effective_tool_config("my_section")
    limit = config["config"].get("limit", 10)
    
    # Get managed client
    client = get_client("my_client")
    results = await client.search(query, limit=limit)
    return ok(results)

Sub-Agent Configuration

Sub-agents are invoked as tools by the master agent:

agents:
  sub_agent:
    llm_profile_name: "default"
    name: "Sub Agent"
    system_prompt_file: "manifest/prompts/sub_agent.md"
    tools:
      - tool_a
      - tool_b
    
    as_subagent:
      tool_name: "invoke_sub_agent"
      tool_description: "Invoke the sub-agent for specialized tasks."
      tool_parameters:
        query:
          type: string
          description: "The query to process"
          required: true
      response_handling: last_artifact  # none | parse_json | last_artifact
      auto_load_artifacts: true

Core Concepts

DeepAgentSession

The main entry point for agent interaction:

• Workspace Management: Persistent storage for artifacts and state
• Planning: Built-in task planning with update_plan tool
• Context Compaction: Automatic long conversation management
• Observability: Logging and OpenTelemetry tracing

Workspace

Each session has an isolated workspace:

.ws/{workspace_id}/
├── {agent_id}/
│   └── plan.json           # Execution plan
├── {artifact_id}/
│   ├── data.json           # Artifact data
│   └── .manifest.json      # Metadata

Artifacts

Large tool outputs are persisted as artifacts:

from agentic_ai.artifacts import persist, load_artifact

# Persist data
result = persist(data=large_data, summary={"rows": 1000})

# Load in another tool
data = load_artifact(artifact_id)

ToolResult Structure

Field	Description
status	"ok" or "error"
result	Data returned to LLM
artifact_id	Artifact ID for persisted data
summary	Metadata summary
is_preview	Whether it's preview data
error_message	Error message (when status="error")

API Reference

Package Structure

agentic_ai/
├── agent/          # Agent core (DeepAgentSession, SubAgentController)
├── config/         # Configuration (AgentConfig, BaseAppConfig)
├── runtime/        # Runtime (bootstrap, session factory, tool context)
├── middleware/     # Middleware (persistence, loader)
├── tools/          # Tool management (loader, manifest)
├── llm/            # LLM (client factory, embedding)
├── artifacts/      # Artifact storage (persist, load, ToolResult)
├── workspace/      # Workspace management
├── planning/       # Planning subsystem
├── observability/  # Logging and tracing
├── mcp/            # Model Context Protocol
├── genui/          # Generative UI (insight reports)
└── ag_ui/          # AG-UI protocol adapter

Agent Builders

Function	Description
build_agent()	Create session with chat client
build_agent_with_llm()	Create session with LLM factory
build_agent_from_config()	Create session from AgentConfig
build_agent_from_store()	Create session from config store
build_agent_session()	Low-level session builder

Artifact API

Function	Description
persist()	Persist data to artifact, return ToolResult
ok()	Create success ToolResult
error()	Create error ToolResult
load_artifact()	Load artifact data by ID
try_load_artifact()	Load artifact, return None if not found

Runtime API

Function	Description
bootstrap_runtime()	Load configs and create RuntimeContext
build_session()	Build agent session from runtime context
ctx()	Get current tool execution context
get_effective_tool_config()	Get merged tool configuration
get_client()	Get managed client instance
tool_handler()	Decorator for auto exception handling

Observability API

Function	Description
setup_logging()	Configure logging
enable_observability()	Enable OpenTelemetry tracing
get_tracer()	Get OpenTelemetry tracer
trace_http_request()	Trace HTTP requests
trace_database_query()	Trace database queries

CLI Commands

# Run agent interactively
agentic-ai run --agent <agent_id> --config <config_path>

# Start AG-UI server
agentic-ai serve --port 8000 --host 0.0.0.0

# Options
--config, -c      Config file path (default: env.yaml)
--manifest-dir    Manifest directory (default: manifest)
--workspace       Workspace root (default: .ws)
--verbose         Enable debug logging

Docker Deployment

# docker-compose.yaml
version: '3.8'
services:
  backend:
    image: agentic-analyst:latest
    ports:
      - "8000:8000"
    volumes:
      - ./env.yaml:/app/env.yaml
      - ./manifest:/app/manifest
      - ./.ws:/app/.ws

  web:
    image: agentic-ai-web-default:latest
    ports:
      - "3000:3000"
    environment:
      - AGENT_BACKEND_URL=http://backend:8000/
    depends_on:
      - backend

Documentation

• Development Guide: Comprehensive development guide
• Tool Result Control: Artifact and result handling

License

MIT License - see LICENSE for details.