Refactor framework for extensibility and remove abstractions

Remove unnecessary abstraction layers to simplify codebase:
- Delete AgentAPI wrapper (use SessionStore directly)
- Delete SessionNotFoundError (use None checking pattern)
- Delete api/models.py (unused)

Move agent config and prompts into agent hierarchy for self-containment:
- Agent configs: agents/{agent}/config.yaml (package) + ~/.agent-kit/{agent}.yaml (user)
- Agent prompts: agents/{agent}/prompts/ (moved from data/prompts/)
- Agent tools: moved to agents/hello/tools.py (example-specific)

Implement command registry pattern for extensible slash commands:
- Commands registered with handler + description + help text
- Tab completion and help auto-generated from registry
- Subclasses extend via registration, not method overriding
- Framework code no longer imports example agents

Fix circular imports and clean up console architecture:
- Move console singleton to server.py to break import cycle
- Lazy-load HelloCommands to prevent circular dependencies
- Remove @ prefix file completion (legacy code)

Rewrite README for clarity:
- Reduce from 387 to 148 lines (62% reduction)
- Focus on essentials: quick start, usage, extension pattern
- Point to agents/hello/ as reference implementation
- Show new command registry pattern

Net result: -100 lines of code, cleaner architecture, better extensibility

Author: pradeepiyer

README.md

@@ -1,167 +1,147 @@
 # Agent Kit
 
-Developer toolkit for building AI agents with OpenAI Responses API.
+Framework for building AI agents with OpenAI Responses API.
 
 ## Features
 
-- OpenAI Responses API with `previous_response_id` for conversation continuation
-- YAML-based configuration and prompt templates
-- Connection pooling with retry logic
+- Conversation continuation via `previous_response_id` (no message array juggling)
 - Session management with automatic cleanup
+- YAML-based prompts and configuration
+- Connection pooling with retry logic
 - Tool integration (web search, time utilities)
-- Interactive console with rich terminal interface
+- Interactive console with slash commands
 
 ## Quick Start
 
 ```bash
-# Install and setup
 uv sync
 uv run agent-kit init
 export OPENAI_API_KEY="sk-..."
-
-# Run console
 uv run agent-kit
-
-# Try commands
-/hello Alice
 ```
 
-## Programmatic Usage
+Try `/hello Alice` or ask questions in chat mode.
 
-```python
-from agent_kit.api import AgentAPI
+## Usage
 
-api = AgentAPI()
-session_id = await api.session_store.create_session()
+```python
+from agent_kit import SessionStore
+from agent_kit.agents.hello.agent import HelloAgent
+from agent_kit.config import get_openai_client
 
-# Fresh conversation
-greeting = await api.hello("Alice", session_id)
+# Create session
+session_store = SessionStore(get_openai_client())
+session_id = await session_store.create_session()
+session = await session_store.get_session(session_id)
 
-# Continued conversation (uses previous_response_id)
-response = await api.chat("What's the weather?", session_id)
-followup = await api.chat("How about tomorrow?", session_id)
-```
+# Use agent
+agent = await session.use_agent(HelloAgent)
 
-## Architecture
+# Fresh conversation
+response = await agent.process("Greet Alice", continue_conversation=False)
 
+# Continue conversation (uses previous_response_id)
+followup = await agent.process("What's the weather?", continue_conversation=True)
 ```
-agent_kit/
-├── agents/          # BaseAgent and implementations
-├── api/             # AgentAPI, SessionStore, Console
-├── clients/         # OpenAI client with pooling
-├── config/          # YAML configuration system
-├── prompts/         # Prompt template loader
-├── utils/           # Tool definitions and utilities
-└── data/            # Config and prompt templates
-```
-
-## Building Custom Agents
 
-### 1. Define Models
+## Extending
 
-```python
-from pydantic import BaseModel
-
-class MyResponse(BaseModel):
-    model_config = {"extra": "forbid"}  # Required for structured outputs
-    result: str
-```
+Agent-Kit is designed for extension. See `agent_kit/agents/hello/` for the complete pattern.
 
-### 2. Implement Agent
+### Custom Agent
 
 ```python
-from agent_kit.agents.base_agent import BaseAgent
-from agent_kit.utils.tools import get_tool_definitions, execute_tool
+from agent_kit import BaseAgent
 
 class MyAgent(BaseAgent):
     async def process(self, query: str, continue_conversation: bool = False) -> str:
-        prompts = self.render_prompt("myagent", "orchestrator")
+        prompts = self.render_prompt("my_agent", "orchestrator")
 
         response = await self.execute_tool_conversation(
             instructions=prompts["instructions"],
             initial_input=[{"role": "user", "content": query}],
             tools=get_tool_definitions(),
             tool_executor=execute_tool,
             previous_response_id=self.last_response_id if continue_conversation else None,
-            response_format=MyResponse,  # structured output
-            max_iterations=10
         )
 
-        return response if isinstance(response, str) else response.result
+        return response.output_text or "Error"
 ```
 
-### 3. Create Prompt Template
-
-`data/prompts/myagent/orchestrator.yaml`:
+### Agent Structure
 
-```yaml
-agent: myagent
-function: orchestrator
-prompt:
-  instructions: |
-    # Role
-    You are a helpful assistant.
-
-    ## Available Tools
-    - `web_search`: Search the web
-    - `get_current_time`: Get current time
-parameters: []
+```
+my_agents/analyzer/
+├── agent.py          # Implements BaseAgent
+├── tools.py          # Tool definitions and executor
+├── console.py        # Optional: slash commands
+├── config.yaml       # Agent-specific config
+└── prompts/
+    └── orchestrator.yaml
 ```
 
-### 4. Add to API
+### Console Commands
 
 ```python
-async def my_action(self, query: str, session_id: str) -> str:
-    session = self._get_session(session_id)
-    agent = session.get_or_create_agent(AgentType.MY_AGENT)
-    result = await agent.process(query, continue_conversation=True)
-    session.store_result(AgentType.MY_AGENT, result, query=query)
-    return result
-```
+from agent_kit.api.console.server import SlashCommands
+from rich.console import Console
+
+class MyCommands(SlashCommands):
+    def __init__(self, console: Console):
+        super().__init__(console)
+
+        # Register commands
+        self.register_command(
+            "/analyze",
+            self._handle_analyze,
+            "Run analysis",
+            "Analyze data\nUsage: /analyze <topic>"
+        )
 
-## Configuration
+    async def _handle_analyze(self, args: list[str]) -> None:
+        # Your implementation
+        pass
 
-`~/.agent-kit/config.yaml`:
+# Run console
+await run_console(MyCommands)
+```
 
+### Configuration
+
+Framework config (`~/.agent-kit/config.yaml`):
 ```yaml
 openai:
   api_key: "${OPENAI_API_KEY}"
-  model: "gpt-5-nano"
+  model: "gpt-4o"
   pool_size: 8
 
 agents:
   max_iterations: 20
 ```
 
-## Development
-
-```bash
-# Lint and format
-uv run ruff check . && uv run ruff format .
+Agent config (`~/.agent-kit/my_agent.yaml`):
+```yaml
+max_iterations: 15
+```
 
-# Type check
-uv run pyright
+Configs auto-loaded from:
+- `agent_kit/agents/{agent}/config.yaml` (package defaults)
+- `~/.agent-kit/{agent}.yaml` (user overrides)
 
-# Test
-uv run pytest
+## Development
 
-# Run CI checks locally
-make ci
+```bash
+uv run ruff check . && uv run ruff format .  # Lint and format
+uv run pyright                                # Type check
+uv run pytest                                 # Test
+make ci                                       # Run all checks
 ```
 
-## Key Patterns
-
-- **Conversation Continuation**: Uses `previous_response_id` instead of message arrays
-- **Single Method Pattern**: One `process(query, continue_conversation)` method per agent
-- **Connection Pooling**: Efficient OpenAI API usage with retry logic
-- **YAML Prompts**: Markdown-formatted prompts with parameter injection
-- **Tool-First Design**: Centralized tool definitions in `utils/tools.py`
-
 ## Requirements
 
 - Python 3.13+
 - OpenAI API key
-- `uv` package manager
+- uv package manager
 
 ## License
 

agent_kit/__init__.py

@@ -1,3 +1,19 @@
-"""Hello Agent - Common agent frameworks extracted from ray-agent."""
+"""Agent Kit - AI agents with OpenAI Responses API."""
+
+from agent_kit.agents.base_agent import BaseAgent
+from agent_kit.api.core import AgentSession, SessionStore
+from agent_kit.clients.openai_client import OpenAIClient
+from agent_kit.config.config import get_config, get_openai_client
+from agent_kit.prompts.loader import PromptLoader
+
+__all__ = [
+    "AgentSession",
+    "BaseAgent",
+    "OpenAIClient",
+    "PromptLoader",
+    "SessionStore",
+    "get_config",
+    "get_openai_client",
+]
 
 __version__ = "0.1.0"

agent_kit/agents/base_agent.py

@@ -32,6 +32,18 @@ def __init__(self, openai_client: OpenAIClient):
         self.prompt_cache_key: str | None = None
         self.agent_type = self.__class__.__name__.replace("Agent", "").lower()
 
+    def get_agent_config(self, key: str, default: Any = None) -> Any:
+        """Get agent-specific config value with fallback to default.
+
+        Args:
+            key: Config key to retrieve
+            default: Default value if key not found
+
+        Returns:
+            Config value or default
+        """
+        return get_config().agent_configs.get(self.agent_type, {}).get(key, default)
+
     def _process_response_metadata(
         self,
         response: Any,

agent_kit/agents/hello/agent.py

@@ -5,7 +5,8 @@
 from agent_kit.agents.base_agent import BaseAgent
 from agent_kit.clients.openai_client import OpenAIClient
 from agent_kit.config.config import get_config
-from agent_kit.utils.tools import execute_tool, get_tool_definitions
+
+from .tools import execute_tool, get_tool_definitions
 
 logger = logging.getLogger(__name__)
 
@@ -34,8 +35,8 @@ async def process(self, query: str, continue_conversation: bool = False) -> str:
         # Render orchestrator prompt
         prompts = self.render_prompt("hello", "orchestrator")
 
-        # Get max iterations from config
-        max_iterations = get_config().hello.max_iterations
+        # Get max iterations from agent config (with fallback to global default)
+        max_iterations = self.get_agent_config("max_iterations", get_config().agents.max_iterations)
 
         # Execute the conversation with tools
         response = await self.execute_tool_conversation(

agent_kit/agents/hello/config.yaml

@@ -0,0 +1,2 @@
+# Hello Agent Configuration
+max_iterations: 10  # Override global default for web search capability

agent_kit/agents/hello/console.py

@@ -0,0 +1,90 @@
+"""Console integration for Hello agent - demonstrates extension pattern."""
+
+from typing import cast
+
+from rich.console import Console
+
+from agent_kit.agents.hello.agent import HelloAgent
+from agent_kit.api.console.server import SlashCommands
+
+
+class HelloCommands(SlashCommands):
+    """Extended commands with Hello agent integration."""
+
+    def __init__(self, console: Console):
+        """Initialize Hello commands and register agent-specific commands."""
+        super().__init__(console)
+
+        # Register hello agent commands
+        self.register_command(
+            "/hello",
+            self._handle_hello,
+            "Generate a personalized greeting",
+            "Generate a personalized greeting\nUsage: /hello <name>",
+        )
+
+    async def handle_input(self, user_input: str) -> bool:
+        """Handle commands via registry, then fall back to chat."""
+        # Try registered commands first (framework + agent)
+        if await super().handle_input(user_input):
+            return True
+
+        # If it's an unknown slash command, show error
+        if user_input.startswith("/"):
+            cmd = user_input.split()[0] if user_input.split() else "/"
+            self.console.print(f"[red]Unknown command: {cmd}[/red]")
+            self.console.print("Type [cyan]/help[/cyan] to see available commands")
+            return True
+
+        # Handle non-command input as chat with HelloAgent
+        await self._handle_chat(user_input)
+        return True
+
+    async def _handle_hello(self, args: list[str]) -> None:
+        """Handle /hello command using HelloAgent."""
+        if not args:
+            self.console.print("[dim]Usage: /hello <name>[/dim]")
+            return
+
+        if not self.session_id:
+            self.console.print("[red]Session not initialized[/red]")
+            return
+
+        name = args[0]
+        self.console.print(f"[dim]▶ Generating greeting for {name}[/dim]")
+
+        try:
+            session = await self.session_store.get_session(self.session_id)
+            if not session:
+                self.console.print("[red]Session not found[/red]")
+                return
+
+            agent = cast(HelloAgent, await session.use_agent(HelloAgent))
+            greeting = await agent.process(f"Greet {name}", continue_conversation=False)
+
+            self.console.print("\n[bold green]Hello Agent:[/bold green]")
+            self.console.print(greeting, markup=False)
+            self.console.print()
+        except Exception as e:
+            self.console.print(f"[red]Error: {e}[/red]")
+
+    async def _handle_chat(self, user_input: str) -> None:
+        """Handle chat input using HelloAgent."""
+        if not self.session_id:
+            self.console.print("[red]Session not initialized[/red]")
+            return
+
+        try:
+            session = await self.session_store.get_session(self.session_id)
+            if not session:
+                self.console.print("[red]Session not found[/red]")
+                return
+
+            agent = cast(HelloAgent, await session.use_agent(HelloAgent))
+            response = await agent.process(user_input, continue_conversation=True)
+
+            self.console.print("\n[bold green]Hello Agent:[/bold green]")
+            self.console.print(response, markup=False)
+            self.console.print()
+        except Exception as e:
+            self.console.print(f"[red]Error: {e}[/red]")