Skip to content
BranchesTags

Repository files navigation

Agentic Runtime

Ask DeepWiki

A state-of-the-art agentic runtime built on the Agno framework with portable model providers, configurable sandbox execution, MCP support, RAG, multi-agent teams, and more.

Features

  • Agentic Coding - File operations, code search, and git integration for autonomous coding tasks
  • Portable Model Providers - Switch between OpenRouter, OpenAI, Anthropic, Google, Ollama, Groq, DeepSeek, Moonshot, Mistral, and xAI via policy
  • Code Execution - Configurable sandbox policy with Daytona support today and explicit local or Docker modes
  • Multi-Agent Teams - Coordinate multiple specialized agents with leader delegation
  • Workflows - Orchestrate complex multi-step tasks with dependencies
  • Knowledge Base (RAG) - Vector database integration with LanceDB, PgVector, Chroma, Qdrant
  • Structured Output - Pydantic-validated responses with JSON mode
  • Reasoning - Chain-of-thought (basic, extended, tools modes)
  • MCP Integration - Model Context Protocol tools with multi-server support
  • Observability - Tool hooks, event streaming, logging, and metrics

Setup

# Clone and install
cp .env.example .env
# Fill in the keys for the provider/sandbox you plan to use

# Basic installation
uv sync

# With knowledge/RAG support
uv sync --extra knowledge

# Full installation (all vector DBs)
uv sync --extra full

# Development (includes pytest, ruff)
uv sync --extra dev

Quick Start

Basic Agent

from core import build_agent, AgentSpec

# Defaults: OpenRouter provider + google/gemini-3.6-flash model
agent = build_agent(AgentSpec())
agent.print_response("What is the capital of France?", stream=True)

Provider Portability

from core import AgentSpec, build_agent
from core.policies import ModelProviderPolicy

# Direct OpenAI
openai_agent = build_agent(
    AgentSpec(
        model_id="gpt-5.6-terra",
        model_provider=ModelProviderPolicy(provider="openai"),
    )
)

# Local Ollama
ollama_agent = build_agent(
    AgentSpec(
        model_id="llama3.1",
        model_provider=ModelProviderPolicy(
            provider="ollama",
            base_url="http://localhost:11434",
        ),
    )
)

Code Execution Agent

from core import build_agent, AgentSpec, CodeActPolicy

spec = AgentSpec(
    codeact=CodeActPolicy(enabled=True, max_iterations=10)
)
agent = build_agent(spec)
agent.print_response("Calculate the first 10 Fibonacci numbers", stream=True)

Structured Output

from pydantic import BaseModel
from core import build_agent, AgentSpec

class Analysis(BaseModel):
    summary: str
    sentiment: str
    confidence: float

spec = AgentSpec().with_output_schema(Analysis)
agent = build_agent(spec)
response = agent.run("Analyze: 'This product is amazing!'")
print(response.content)  # Validated Analysis object

Multi-Agent Team

from core import build_team, AgentSpec, AgentRole, TeamPolicy

members = [
    AgentRole(name="researcher", role="Research topics"),
    AgentRole(name="writer", role="Write content"),
]

spec = AgentSpec(
    team=TeamPolicy(
        enabled=True,
        members=members,
        leader_instructions=["Coordinate research and writing"],
    )
)
team = build_team(spec)
team.print_response("Research and write about quantum computing", stream=True)

With Reasoning

from core import build_agent, AgentSpec, ReasoningPolicy

spec = AgentSpec(
    reasoning=ReasoningPolicy(enabled=True, mode="extended")
)
agent = build_agent(spec)
agent.print_response("Solve this step by step: ...", stream=True)

Agentic Coding Agent (Policy-Driven Sandbox)

from core import AgentSpec, build_agent
from core.policies import CodeActPolicy, ModelProviderPolicy, SystemPromptPolicy

agent = build_agent(
    AgentSpec(
        name="coding_agent",
        model_id="anthropic/claude-sonnet-5",
        model_provider=ModelProviderPolicy(provider="openrouter"),
        codeact=CodeActPolicy(
            enabled=True,
            sandbox="daytona",
            sandbox_timeout_minutes=60,
        ),
        system_prompt=SystemPromptPolicy(
            template="custom",
            custom_template="You work in a sandbox at /home/daytona. Clone repos with: git clone <url> /home/daytona/repo",
        ),
    )
)

agent.print_response(
    "Clone https://github.com/user/repo.git, list the structure, and analyze the README",
    stream=True,
)

Configuration

All configuration is done through AgentSpec and its policies:

from core import (
    AgentSpec,
    ContextPolicy,
    ToolPolicy,
    CodeActPolicy,
    CodingPolicy,
    McpPolicy,
    ModelProviderPolicy,
    KnowledgePolicy,
    ReasoningPolicy,
    StoragePolicy,
    TeamPolicy,
    WorkflowPolicy,
    ObservabilityPolicy,
    SystemPromptPolicy,
)

spec = AgentSpec(
    name="my_agent",
    model_id="google/gemini-3.6-flash",

    # Model provider
    model_provider=ModelProviderPolicy(
        provider="openrouter",
    ),

    # Runtime storage
    storage=StoragePolicy(
        db_file="tmp/agents.db",
    ),
    
    # Context and memory
    context=ContextPolicy(
        enable_user_memories=True,
        num_history_runs=5,
    ),
    
    # Code execution
    codeact=CodeActPolicy(
        enabled=True,
        sandbox="daytona",  # daytona, local, docker
        max_iterations=10,
        extract_charts=True,
    ),
    
    # Knowledge base (RAG)
    knowledge=KnowledgePolicy(
        enabled=True,
        vector_db="lancedb",  # lancedb, pgvector, chroma, qdrant
        search_type="hybrid",
    ),
    
    # Reasoning
    reasoning=ReasoningPolicy(
        enabled=True,
        mode="extended",  # basic, extended, tools
    ),
    
    # Agentic coding (local file ops)
    coding=CodingPolicy(
        enabled=True,
        workspace_root="/path/to/project",
        allow_write=True,
        enable_git=True,
    ),
    
    # Observability
    observability=ObservabilityPolicy(
        log_tool_calls=True,
        debug_mode=True,
    ),
)

Portability Notes

  • model_provider.provider defaults to openrouter for backward compatibility
  • codeact.sandbox defaults to daytona; local disables sandbox tools and docker is reserved for future implementation
  • storage.db_file defaults to tmp/agents.db
  • storage.db_url is reserved for future remote database support and currently raises if configured

Current Model Aliases

Portable aliases map to provider-specific IDs when the agent is built:

Alias OpenRouter ID Native provider
kimi-k3 moonshotai/kimi-k3 moonshot / kimi-k3
deepseek-v4-flash deepseek/deepseek-v4-flash-0731 deepseek / deepseek-v4-flash 
from core import AgentSpec, ModelProviderPolicy, build_agent

# Uses moonshotai/kimi-k3 through the default OpenRouter provider.
kimi = build_agent(AgentSpec(model_id="kimi-k3"))

# Uses DeepSeek's native API and model ID.
deepseek = build_agent(
    AgentSpec(
        model_id="deepseek-v4-flash",
        model_provider=ModelProviderPolicy(provider="deepseek"),
    )
)

Presets

Use convenience functions for common configurations:

from core import (
    create_basic_spec,
    create_codeact_spec,
    create_research_spec,
    create_coding_spec,
    create_team_spec,
)

# Basic agent (no code execution)
spec = create_basic_spec()

# Code execution agent (Daytona by default)
spec = create_codeact_spec(max_iterations=10)

# Research agent with RAG and extended reasoning
spec = create_research_spec(
    knowledge_sources=["https://docs.example.com"]
)

# Agentic coding agent (file ops + git + code execution)
spec = create_coding_spec(
    workspace_root=".",
    enable_codeact=True,
    allow_write=True,
    allow_git_write=False,
)

# Multi-agent team
from core import AgentRole
spec = create_team_spec(
    members=[
        AgentRole(name="analyst", role="Analyze data"),
        AgentRole(name="reporter", role="Write reports"),
    ]
)

Examples

See the examples/ directory for complete examples:

Example Description
01_basic_agent.py Simple Q&A agent
02_code_execution_agent.py Code execution with policy-driven sandbox config
03_data_analysis_agent.py Data analysis and charts
04_mcp_agent.py MCP tool integration
05_full_featured_agent.py All features combined
06_conversational_session.py Interactive chat
07_structured_output.py Pydantic-validated responses
08_multi_agent_team.py Multi-agent coordination
09_agentic_coding_agent.py Agentic coding through AgentSpec + Daytona sandbox
10_xlsx_skill_agent.py Validate a workbook with the xlsx skill 
# Run basic example
uv run python examples/01_basic_agent.py

# Run agentic coding agent (uses the runtime's policy-driven Daytona path)
uv run python examples/09_agentic_coding_agent.py --mode analyze
uv run python examples/09_agentic_coding_agent.py --mode refactor
uv run python examples/09_agentic_coding_agent.py --mode test
uv run python examples/09_agentic_coding_agent.py --mode feature
uv run python examples/09_agentic_coding_agent.py --mode interactive

# Use a custom GitHub repository
uv run python examples/09_agentic_coding_agent.py --repo https://github.com/owner/repo.git --branch main

# Prepare and run the xlsx skill example
uv run python examples/10_xlsx_skill_agent.py --prepare-only
uv run python examples/10_xlsx_skill_agent.py

The xlsx skill example expects the skill at ~/.agents/skills/xlsx by default and looks for LibreOffice via soffice, SOFFICE_BIN, or --soffice-path.

Testing

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_policies.py

Architecture

core/
├── __init__.py          # Public API exports
├── factory.py           # build_agent, build_team, build_workflow, provider/storage resolution
├── policies.py          # All configuration policies & presets
├── context_manager.py   # Context management utilities
├── settings.py          # Environment settings
├── tool_runtime.py      # Tool runtime utilities
├── prompts/
│   └── system.py        # System prompt templates with backend-aware code execution text
└── tools/
    ├── local.py         # Local utility tools
    ├── daytona.py       # Daytona sandbox integration
    ├── sandbox.py       # Sandbox backend dispatcher
    ├── coding.py        # File operations & code search
    ├── git.py           # Git integration tools
    ├── mcp.py           # MCP tool integration
    ├── knowledge.py     # RAG/knowledge tools
    ├── reasoning.py     # Reasoning tools
    └── hooks.py         # Observability hooks

Coding Tools

Tool Description
read_file Read file contents with optional line range
write_file Create or overwrite files
edit_file Edit files by replacing text (single or all occurrences)
list_directory List directory contents
find_files Find files matching glob patterns
grep Regex-based code search with context
get_file_info Get file metadata (size, type, etc.)

Git Tools

Tool Description
git_status Show working tree status
git_diff Show changes between commits or working tree
git_log Show commit history
git_branch List branches
git_show Show commit details
git_blame Show line-by-line authorship
git_add Stage files (if allow_git_write=True)
git_commit Create commits (if allow_git_write=True)

Sandbox Operations

Tool Description
run_shell_command Execute bash commands (git, ls, grep, etc.)
run_code Execute Python code in sandbox
create_file Create or update files in sandbox
read_file Read file contents from sandbox
list_files List directory contents in sandbox
delete_file Delete files in sandbox

These tools are available when codeact.enabled=True and codeact.sandbox="daytona".

Environment Variables

OPENROUTER_API_KEY=...    # Use when model_provider.provider="openrouter"
OPENAI_API_KEY=...        # Use when model_provider.provider="openai"
ANTHROPIC_API_KEY=...     # Use when model_provider.provider="anthropic"
GOOGLE_API_KEY=...        # Use when model_provider.provider="google"
DEEPSEEK_API_KEY=...      # Use when model_provider.provider="deepseek"
MOONSHOT_API_KEY=...      # Use when model_provider.provider="moonshot"
DAYTONA_API_KEY=...       # Required when codeact.sandbox="daytona"
DAYTONA_API_URL=...       # Optional custom Daytona endpoint

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages