spoon-agent-development

Original source / Raw SKILL.md

---
name: spoon-agent-development
description: Build AI agents with SpoonReactMCP. Use when creating custom agents, configuring tool chains, designing system prompts, or implementing concurrent agent patterns.
---

# Agent Development

Build AI agents using the Spoon AI ReAct framework.

## Agent Hierarchy

```
SpoonReactSkill  → Skills + x402 Payments
    ↓
SpoonReactMCP   → MCP Tool Integration
    ↓
SpoonReactAI    → Base ReAct + Tool Calling
    ↓
ToolCallAgent   → Tool Execution
    ↓
BaseAgent       → Pydantic Foundation
```

## Quick Start

```python
from spoon_ai.agents import SpoonReactMCP
from spoon_ai.chat import ChatBot
from spoon_ai.tools import ToolManager
from spoon_ai.tools.mcp_tool import MCPTool

# Create agent with MCP tool
agent = SpoonReactMCP(
    name="my_agent",
    llm=ChatBot(model_name="gpt-4o"),
    tools=ToolManager([MCPTool(...)]),
    max_steps=15
)

await agent.initialize()
result = await agent.run("Your query here")
```

## Scripts

| Script | Purpose |
|--------|---------|
| [basic_agent.py](scripts/basic_agent.py) | Simple SpoonReactAI agent |
| [mcp_agent.py](scripts/mcp_agent.py) | MCP-enabled agent |
| [custom_tool.py](scripts/custom_tool.py) | Custom BaseTool implementation |
| [concurrent_agents.py](scripts/concurrent_agents.py) | Multi-agent parallel execution |

## References

| Reference | Content |
|-----------|---------|
| [prompts.md](references/prompts.md) | System prompt templates |
| [mcp_config.md](references/mcp_config.md) | MCP configuration options |

## Configuration

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `name` | str | "spoon_react" | Agent identifier |
| `max_steps` | int | 10 | Max ReAct iterations |
| `tool_choice` | str | "required" | "auto", "required", "none" |
| `system_prompt` | str | None | Custom system prompt |

## Best Practices

1. Pre-load MCP tool parameters before use
2. Use concurrent execution for independent tools
3. Implement retry with exponential backoff
4. Keep system prompts focused and specific
5. Never hardcode API keys


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/basic_agent.py

```python
#!/usr/bin/env python3
"""Basic SpoonReactAI agent example."""

from spoon_ai.agents import SpoonReactAI
from spoon_ai.chat import ChatBot
from spoon_ai.tools import ToolManager
from spoon_ai.tools.base import BaseTool
from pydantic import Field


class PriceTool(BaseTool):
    """Custom tool for fetching crypto prices."""
    name: str = "get_crypto_price"
    description: str = "Get the current price of a cryptocurrency"
    parameters: dict = Field(default={
        "type": "object",
        "properties": {
            "symbol": {
                "type": "string",
                "description": "Cryptocurrency symbol (e.g., BTC, ETH)"
            }
        },
        "required": ["symbol"]
    })

    async def execute(self, symbol: str) -> str:
        # Replace with actual API call
        return f"Price of {symbol}: $50000"


class CryptoAnalysisAgent(SpoonReactAI):
    """Agent specialized for cryptocurrency analysis."""

    name: str = "crypto_analyst"
    description: str = "An AI agent specialized in crypto market analysis"
    max_steps: int = 15
    tool_choice: str = "required"

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.llm = ChatBot(model_name="gpt-4o", llm_provider="openai")
        self.available_tools = ToolManager([PriceTool()])
        self.system_prompt = """You are a cryptocurrency market analyst.
Your role is to:
- Analyze market trends and provide insights
- Fetch real-time price data using available tools
- Explain technical indicators clearly
- Always include risk warnings in trading advice"""


async def main():
    agent = CryptoAnalysisAgent()
    await agent.initialize()
    result = await agent.run("What's the current price of Bitcoin?")
    print(result)


if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

```

### scripts/mcp_agent.py

```python
#!/usr/bin/env python3
"""MCP-enabled SpoonReactMCP agent example."""

import os
import asyncio
from spoon_ai.agents import SpoonReactMCP
from spoon_ai.chat import ChatBot
from spoon_ai.tools import ToolManager
from spoon_ai.tools.mcp_tool import MCPTool


# NPX-based MCP tool
tavily_search = MCPTool(
    name="tavily-search",
    description="Search the web for current information",
    mcp_config={
        "command": "npx",
        "args": ["-y", "tavily-mcp"],
        "env": {"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY")},
        "timeout": 30,
        "max_retries": 3,
    },
)

# Python-based MCP tool
python_tool = MCPTool(
    name="data-analysis",
    description="Analyze data with custom Python MCP server",
    mcp_config={
        "command": "python",
        "args": ["path/to/mcp_server.py"],
        "env": {"DATA_PATH": "/data"}
    }
)

# URL-based MCP tool (SSE)
sse_tool = MCPTool(
    name="remote-service",
    description="Connect to remote MCP service",
    mcp_config={
        "url": "https://mcp.example.com/sse",
        "transport": "sse"
    }
)


async def main():
    # Create agent with MCP tools
    agent = SpoonReactMCP(
        name="research_agent",
        llm=ChatBot(model_name="gpt-4o", llm_provider="openai"),
        tools=ToolManager([tavily_search]),
        max_steps=15
    )

    # Pre-load MCP tool parameters (important for schema discovery)
    await tavily_search.ensure_parameters_loaded()

    # Initialize agent
    await agent.initialize()

    # Execute query
    result = await agent.run("Find the latest news about Ethereum ETF approval")
    print(result)


if __name__ == "__main__":
    asyncio.run(main())

```

### scripts/concurrent_agents.py

```python
#!/usr/bin/env python3
"""Concurrent agent execution patterns."""

import asyncio
from spoon_ai.agents import SpoonReactMCP
from spoon_ai.tools import ToolManager


async def execute_tools_concurrently(manager: ToolManager, tasks: list):
    """Execute multiple tool calls concurrently."""

    async def execute_single(task):
        name, inputs = task["name"], task["inputs"]
        try:
            result = await manager.execute(name=name, tool_input=inputs)
            return {"name": name, "success": True, "result": result}
        except Exception as e:
            return {"name": name, "success": False, "error": str(e)}

    results = await asyncio.gather(
        *[execute_single(task) for task in tasks],
        return_exceptions=True
    )
    return results


async def run_agents_concurrently(agents: list, queries: list):
    """Run multiple agents concurrently with different queries."""

    async def run_single(agent, query):
        try:
            await agent.initialize()
            result = await agent.run(query)
            return {"agent": agent.name, "success": True, "result": result}
        except Exception as e:
            return {"agent": agent.name, "success": False, "error": str(e)}

    if len(agents) != len(queries):
        raise ValueError("Number of agents must match number of queries")

    results = await asyncio.gather(
        *[run_single(agent, query) for agent, query in zip(agents, queries)],
        return_exceptions=True
    )
    return results


async def main():
    # Create specialized agents
    research_agent = SpoonReactMCP(name="researcher", max_steps=10)
    analysis_agent = SpoonReactMCP(name="analyst", max_steps=10)
    summary_agent = SpoonReactMCP(name="summarizer", max_steps=5)

    # Run concurrently
    results = await run_agents_concurrently(
        agents=[research_agent, analysis_agent, summary_agent],
        queries=[
            "Find latest DeFi trends",
            "Analyze BTC price movements",
            "Summarize today's crypto news"
        ]
    )

    for result in results:
        print(f"{result['agent']}: {result.get('result', result.get('error'))}")


if __name__ == "__main__":
    asyncio.run(main())

```

### references/prompts.md

```markdown
# System Prompt Templates

## Role-Based Prompt

```python
ROLE_BASED_PROMPT = """You are {role_name}, an AI assistant specialized in {domain}.

## Core Responsibilities
- {responsibility_1}
- {responsibility_2}
- {responsibility_3}

## Communication Style
- Be {tone} and {style}
- {formatting_guidelines}

## Constraints
- {constraint_1}
- {constraint_2}

## Available Tools
{tool_list}
"""
```

## Task-Oriented Prompt

```python
TASK_ORIENTED_PROMPT = """You are an AI assistant focused on {task_category}.

## Your Mission
{mission_statement}

## Step-by-Step Approach
1. Understand the user's request
2. Break down complex tasks into smaller steps
3. Use available tools when necessary
4. Validate results before responding
5. Provide clear, actionable outputs

## Tool Usage Guidelines
- Use {tool_name} for {use_case}
- Always verify tool outputs
- Handle errors gracefully

## Output Format
{output_format_specification}
"""
```

## Dynamic Prompt with Tool List

```python
class DynamicPromptAgent(SpoonReactAI):
    def _build_tool_list(self) -> str:
        if not self.available_tools or not self.available_tools.tool_map:
            return "- (no tools loaded)"

        lines = []
        for tool in self.available_tools.tool_map.values():
            desc = getattr(tool, "description", "") or ""
            lines.append(f"- {tool.name}: {desc}")
        return "\n".join(lines)

    def _refresh_prompts(self) -> None:
        tool_list = self._build_tool_list()

        self.system_prompt = f"""You are Spoon AI, an all-capable AI agent.

Available tools:
{tool_list}

Use these tools to efficiently complete complex requests."""
```

```

### references/mcp_config.md

```markdown
# MCP Configuration Reference

## Transport Types

### NPX (Node.js)

```python
mcp_config={
    "command": "npx",
    "args": ["-y", "package-name"],
    "env": {"API_KEY": "..."},
    "timeout": 30,
    "max_retries": 3
}
```

### Python

```python
mcp_config={
    "command": "python",
    "args": ["path/to/server.py"],
    "env": {"DATA_PATH": "/data"}
}
```

### UVX

```python
mcp_config={
    "command": "uvx",
    "args": ["package-name", "--flag"],
    "env": {}
}
```

### SSE (Server-Sent Events)

```python
mcp_config={
    "url": "https://mcp.example.com/sse",
    "transport": "sse"
}
```

### WebSocket

```python
mcp_config={
    "url": "wss://mcp.example.com/ws"
}
```

### HTTP Streamable

```python
mcp_config={
    "url": "https://mcp.example.com/api",
    "transport": "http",
    "headers": {"Authorization": "Bearer token"}
}
```

## Configuration Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `command` | str | - | Command to execute |
| `args` | list | [] | Command arguments |
| `env` | dict | {} | Environment variables |
| `url` | str | - | Server URL (SSE/WS/HTTP) |
| `transport` | str | "sse" | Transport type |
| `timeout` | int | 30 | Connection timeout (seconds) |
| `max_retries` | int | 3 | Max retry attempts |
| `health_check_interval` | int | 300 | Health check interval (seconds) |

```