### Run Didactic Example with DSPy

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/dspy-integration/README.md

Navigate to the example directory, install dependencies, set your OpenAI API key, and run the main didactic example to see DSPy in action.

```bash
cd atomic-examples/dspy-integration

uv sync

export OPENAI_API_KEY="your-key-here"

uv run python -m dspy_integration.main
```

--------------------------------

### Run Example Client with STDIO Transport

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/mcp-agent/README.md

Run the example client using the default STDIO transport. This is the simplest way to get started.

```bash
cd example-client
uv run python -m example_client.main --client stdio
# or simply:
uv run python -m example_client.main
```

--------------------------------

### Quickstart: Create and Run an Atomic Agent

Source: https://github.com/eigenwise/atomic-agents/blob/main/README.md

Demonstrates creating a custom agent with a specific output schema, system prompt, and running it with user input. Requires OpenAI client setup.

```python
from pydantic import Field
from openai import OpenAI
import instructor
from atomic_agents import AtomicAgent, AgentConfig, BasicChatInputSchema, BaseIOSchema
from atomic_agents.context import SystemPromptGenerator, ChatHistory

# Define a custom output schema
class CustomOutputSchema(BaseIOSchema):
    """
    docstring for the custom output schema
    """
    chat_message: str = Field(..., description="The chat message from the agent.")
    suggested_questions: list[str] = Field(..., description="Suggested follow-up questions.")

# Set up the system prompt
system_prompt_generator = SystemPromptGenerator(
    background=["This assistant is knowledgeable, helpful, and suggests follow-up questions."],
    steps=[
        "Analyze the user's input to understand the context and intent.",
        "Formulate a relevant and informative response.",
        "Generate 3 suggested follow-up questions for the user."
    ],
    output_instructions=[
        "Provide clear and concise information in response to user queries.",
        "Conclude each response with 3 relevant suggested questions for the user."
    ]
)

# Initialize OpenAI client
client = instructor.from_openai(OpenAI())

# Initialize the agent
agent = AtomicAgent[BasicChatInputSchema, CustomOutputSchema](
    config=AgentConfig(
        client=client,
        model="gpt-5-mini",
        system_prompt_generator=system_prompt_generator,
        history=ChatHistory(),
    )
)

# Example usage
if __name__ == "__main__":
    user_input = "Tell me about atomic agents framework"
    response = agent.run(BasicChatInputSchema(chat_message=user_input))
    print(f"Agent: {response.chat_message}")
    print("Suggested questions:")
    for question in response.suggested_questions:
        print(f"- {question}")
```

--------------------------------

### Set Up Example Client

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/mcp-agent/README.md

Set up the example client by synchronizing its dependencies.

```bash
cd ../example-client
uv sync
```

--------------------------------

### Run Example Client with SSE Transport

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/mcp-agent/README.md

Run the example client and server using the SSE transport. Ensure the server is started before the client.

```bash
# First terminal: Start the server
cd example-mcp-server
uv run python -m example_mcp_server.server --mode=sse

# Second terminal: Run the client with SSE transport
cd example-client
uv run python -m example_client.main --client sse
```

--------------------------------

### Navigate to Quickstart Directory

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/quickstart/README.md

Navigate to the quickstart directory after cloning the repository.

```bash
cd atomic-agents/atomic-examples/quickstart
```

--------------------------------

### Run Example Client with HTTP Stream Transport

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/mcp-agent/README.md

Run the example client and server using the HTTP Stream transport. Ensure the server is started before the client.

```bash
# First terminal: Start the server
cd example-mcp-server
uv run python -m example_mcp_server.server --mode=http_stream

# Second terminal: Run the client with HTTP Stream transport
cd example-client
uv run python -m example_client.main --client http_stream
```

--------------------------------

### Navigate to Example Directory

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/basic-multimodal/README.md

Change the current directory to the basic-multimodal example folder.

```bash
cd atomic-agents/atomic-examples/basic-multimodal
```

--------------------------------

### Navigate to Example Directory

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/basic-pdf-analysis/README.md

Change directory into the specific basic-pdf-analysis example folder.

```bash
cd atomic-agents/atomic-examples/basic-pdf-analysis
```

--------------------------------

### Navigate to Example Directory

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/youtube-to-recipe/README.md

Change directory into the YouTube Recipe Extractor example folder.

```bash
cd atomic-agents/atomic-examples/youtube-to-recipe
```

--------------------------------

### Navigate to Example Directory

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/nested-multimodal/README.md

Change the current directory to the nested-multimodal example folder.

```bash
cd atomic-agents/atomic-examples/nested-multimodal
```

--------------------------------

### Asynchronous Tool Fetching Setup (STDIO)

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/examples/mcp_agent.md

An example of setting up asynchronous fetching of MCP tools, optimized for STDIO transport with persistent sessions. It reuses an existing session object.

```python
# Asynchronous fetching (optimized for STDIO with persistent sessions)
async def setup_tools():
    tools = await fetch_mcp_tools_async(
        transport_type=MCPTransportType.STDIO,
        client_session=session  # Reuse existing session
    )
    return tools
```

--------------------------------

### Install from Eigenwise Marketplace

Source: https://github.com/eigenwise/atomic-agents/blob/main/claude-plugin/atomic-agents/README.md

Use these commands to install the latest version directly from the Eigenwise marketplace. This method ensures you get immediate updates.

```bash
/plugin marketplace add eigenwise/atomic-agents
```

```bash
/plugin install atomic-agents@eigenwise
```

--------------------------------

### Run the Example

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/basic-multimodal/README.md

Execute the main Python script for the basic multimodal example using 'uv run'.

```bash
uv run python basic_multimodal/main.py
```

--------------------------------

### Install All Workspace Packages

Source: https://github.com/eigenwise/atomic-agents/blob/main/README.md

Install all packages within the monorepo, including examples and tools, using 'uv sync --all-packages'. This is useful for comprehensive local development.

```bash
uv sync --all-packages
```

--------------------------------

### Run Basic Chatbot Example

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/quickstart/README.md

Run the basic chatbot example using uv.

```bash
uv run python quickstart/1_0_basic_chatbot.py
```

--------------------------------

### Run Example Client with Async STDIO Transport

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/mcp-agent/README.md

Run the example client using the asynchronous STDIO transport.

```bash
cd example-client
uv run python -m example_client.main --client stdio_async
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/contributing.md

Install project dependencies using the 'uv sync' command. Use 'uv sync --all-packages' to install dependencies for all workspace packages, including examples and tools.

```bash
uv sync
```

```bash
uv sync --all-packages
```

--------------------------------

### Set Up MCP Server

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/mcp-agent/README.md

Set up the example MCP server by synchronizing its dependencies.

```bash
cd example-mcp-server
uv sync
```

--------------------------------

### Run Example with uv

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/quickstart/README.md

General command to run any example file using uv. Replace <example_file_name> with the specific file.

```bash
uv run python quickstart/<example_file_name>.py
```

--------------------------------

### Start MCP Server (SSE Mode)

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/examples/mcp_agent.md

Navigates to the example-mcp-server directory and starts the server in SSE mode.

```bash
cd example-mcp-server
uv run example-mcp-server --mode=sse
```

--------------------------------

### Navigate to Hooks Example Directory

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/hooks-example/README.md

Navigate to the specific directory for the hooks example within the cloned repository.

```bash
cd atomic-agents/atomic-examples/atomic-hooks-example
```

--------------------------------

### Run the Hooks Example

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/hooks-example/README.md

Execute the Python script for the hooks example using uv.

```bash
uv run python hooks_example/main.py
```

--------------------------------

### Run the Orchestration Agent Example

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/orchestration-agent/README.md

Execute the orchestrator script to run the example.

```bash
uv run python orchestration_agent/orchestrator.py
```

--------------------------------

### Run FastAPI Server

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/fastapi-memory/README.md

Start the FastAPI server using uv.

```bash
uv run python fastapi_memory/main.py
```

--------------------------------

### Example Environment Variables File

Source: https://github.com/eigenwise/atomic-agents/blob/main/claude-plugin/atomic-agents/skills/framework/references/project-structure.md

An example `.env.example` file to be committed, showing required environment variables for application configuration. It includes placeholders for API keys and model names.

```bash
OPENAI_API_KEY=sk-...
# ANTHROPIC_API_KEY=...
# GEMINI_API_KEY=...
# GROQ_API_KEY=...
MY_APP_MODEL=gpt-5-mini
```

--------------------------------

### Run the PDF Analysis Example

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/basic-pdf-analysis/README.md

Execute the main Python script for the basic PDF analysis example using uv.

```bash
uv run python basic_pdf_analysis/main.py
```

--------------------------------

### Install from Anthropic's Community Marketplace

Source: https://github.com/eigenwise/atomic-agents/blob/main/claude-plugin/atomic-agents/README.md

After approval in the Anthropic community directory, add the marketplace and install the plugin. This directory is submission-only.

```bash
/plugin marketplace add anthropics/claude-plugins-community
```

```bash
/plugin install atomic-agents@claude-community
```

--------------------------------

### Run the Nested Multimodal Example

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/nested-multimodal/README.md

Execute the main Python script for the nested multimodal example using 'uv run'.

```bash
uv run python nested_multimodal/main.py
```

--------------------------------

### Set Up Pre-commit Hooks

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/contributing.md

Install pre-commit hooks to ensure code quality and consistency before committing changes. Run 'pre-commit install' in the project's root directory.

```bash
pre-commit install
```

--------------------------------

### Run Example Client with FastAPI Client

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/mcp-agent/README.md

Run the example client using the FastAPI client, which requires the server to be running with HTTP Stream mode. Access the API interface via http://localhost:8000.

```bash
# First terminal: Start the MCP server
cd example-mcp-server
uv run python -m example_mcp_server.server --mode=http_stream

# Second terminal: Run the FastAPI client
cd example-client
uv run python -m example_client.main --client fastapi
# Then visit http://localhost:8000 for the API interface
```

--------------------------------

### Example Session Output

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/progressive-disclosure/README.md

This output illustrates an example session of the progressive disclosure demo, showing tool discovery, orchestrator creation, and query execution.

```text
╭──────────────────────────────────────────────────────╮
│ Progressive Disclosure Demo                          │
│ Demonstrating Anthropic's pattern with 3 MCP servers │
╰──────────────────────────────────────────────────────╯

Connecting to MCP servers...
Connecting to math-server...
  Connected: 8 tools
Connecting to text-server...
  Connected: 8 tools
Connecting to data-server...
  Connected: 8 tools

Total: 24 tools across 3 servers

Ready! Type '/exit' to quit, '/stats' for statistics.
Example queries:
  - 'Calculate (5 + 3) * 2'              (math tools)
  - 'Convert HELLO WORLD to lowercase'  (text tools)
  - 'Find the average of [1,2,3,4,5]'   (data tools)
  - 'Reverse the text ABC and add 10+5' (multi-server!)

You: Calculate (5 + 3) * 2

Phase 1: Tool Discovery
Sub-agent searching 24 tools across 3 servers...
Selected 2 tools: ['add_numbers', 'multiply_numbers']
Reasoning: The query requires addition and multiplication operations

Phase 2: Creating Focused Orchestrator
Orchestrator context: 2 tools (filtered 92% = saved ~11000 tokens)

Phase 3: Query Execution
Executing: add_numbers
Parameters: {'a': 5, 'b': 3}
Executing: multiply_numbers
Parameters: {'a': 8, 'b': 2}

Response: The result of (5 + 3) * 2 is 16.

╭──────────────────────────────────────────────────────╮
│ Progressive Disclosure: 2/24 tools loaded (92%)     │
╰──────────────────────────────────────────────────────╯
```

--------------------------------

### Setup OpenTelemetry Tracing

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/guides/logging.md

Configure the OpenTelemetry tracer provider, add an OTLP exporter, and instrument the HTTPX client. This setup is essential for capturing and exporting trace data.

```python
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor


def setup_tracing(service_name: str = "atomic-agents"):
    """Configure OpenTelemetry tracing."""

    # Set up tracer provider
    provider = TracerProvider()

    # Add OTLP exporter (for Jaeger, Zipkin, etc.)
    otlp_exporter = OTLPSpanExporter(
        endpoint="http://localhost:4317",
        insecure=True
    )
    provider.add_span_processor(BatchSpanProcessor(otlp_exporter))

    trace.set_tracer_provider(provider)

    # Instrument HTTP client (used by OpenAI SDK)
    HTTPXClientInstrumentor().instrument()

    return trace.get_tracer(service_name)


tracer = setup_tracing()


class TracedAgent:
    """Agent wrapper with distributed tracing."""

    def __init__(self, agent: AtomicAgent):
        self.agent = agent

    def run(self, input_data):
        """Run with tracing span."""
        with tracer.start_as_current_span("agent.run") as span:
            span.set_attribute("agent.model", self.agent.model)
            span.set_attribute("input.length", len(str(input_data)))

            try:
                response = self.agent.run(input_data)
                span.set_attribute("output.length", len(str(response)))
                span.set_status(trace.Status(trace.StatusCode.OK))
                return response
            except Exception as e:
                span.set_status(trace.Status(trace.StatusCode.ERROR, str(e)))
                span.record_exception(e)
                raise


# Usage
traced_agent = TracedAgent(agent)
```

--------------------------------

### Model-Level Validation with Pydantic

Source: https://github.com/eigenwise/atomic-agents/blob/main/claude-plugin/atomic-agents/skills/framework/references/schemas.md

Employ `model_validator` for cross-field validation. This example ensures that the end date is not before the start date.

```python
from pydantic import model_validator
from datetime import date

class DateRange(BaseIOSchema):
    """An inclusive date range."""
    start: date = Field(..., description="Start date (inclusive).")
    end: date = Field(..., description="End date (inclusive).")

    @model_validator(mode="after")
    def _ordered(self) -> "DateRange":
        if self.end < self.start:
            raise ValueError("end must be on or after start")
        return self
```

--------------------------------

### Python Health Check Implementation

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/guides/deployment.md

Defines Pydantic models for health status and a HealthChecker class to perform API key and agent responsiveness checks. Includes an asynchronous method to get comprehensive health status and an example FastAPI endpoint.

```python
from datetime import datetime
from pydantic import BaseModel


class HealthStatus(BaseModel):
    status: str
    timestamp: str
    checks: dict[str, bool]
    details: dict[str, str] | None = None


class HealthChecker:
    """Performs health checks for agent deployments."""

    def __init__(self, agent: AtomicAgent):
        self.agent = agent
        self.last_successful_request: datetime | None = None

    async def check_agent_health(self) -> bool:
        """Verify agent can process requests."""
        try:
            # Simple test request
            response = await self.agent.run_async(
                BasicChatInputSchema(chat_message="health check")
            )
            self.last_successful_request = datetime.utcnow()
            return bool(response.chat_message)
        except Exception:
            return False

    def check_api_key_valid(self) -> bool:
        """Verify API key is configured."""
        import os
        return bool(os.getenv("OPENAI_API_KEY"))

    async def get_health_status(self) -> HealthStatus:
        """Get comprehensive health status."""
        checks = {
            "api_key_configured": self.check_api_key_valid(),
            "agent_responsive": await self.check_agent_health(),
        }

        status = "healthy" if all(checks.values()) else "unhealthy"

        details = {}
        if self.last_successful_request:
            details["last_success"] = self.last_successful_request.isoformat()

        return HealthStatus(
            status=status,
            timestamp=datetime.utcnow().isoformat(),
            checks=checks,
            details=details if details else None
        )


# Health check endpoint
@app.get("/health", response_model=HealthStatus)
async def health_check():
    return await health_checker.get_health_status()
```

--------------------------------

### Python Usage Example for Wikipedia Search Tool

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-forge/tools/wikipedia_search/README.md

Demonstrates how to instantiate and use the WikipediaSearchTool to search for articles. It shows how to specify search queries, language, and the maximum number of results, and how to iterate through the returned articles to print their titles and summaries. Ensure 'atomic-agents', 'pydantic', and 'aiohttp' are installed.

```python
from tool.wikipedia_search import WikipediaSearchTool, WikipediaSearchToolInputSchema

tool = WikipediaSearchTool()
output = tool.run(WikipediaSearchToolInputSchema(
    queries=["Atomic Agents", "Pydantic"],
    language="en",
    max_results_per_query=2,
))

for article in output.results:
    print(article.title, "->", article.page_url)
    print(article.summary)
```

--------------------------------

### Install Atomic Agents

Source: https://github.com/eigenwise/atomic-agents/blob/main/README.md

Use pip to install the Atomic Agents library. Ensure you also install the desired provider SDK.

```bash
pip install atomic-agents
```

```bash
pip install instructor[groq]        # for Groq
pip install instructor[anthropic]   # for Anthropic
pip install instructor[google-genai] # for Gemini
```

--------------------------------

### Install Atomic Agents

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/index.md

Install the Atomic Agents package using pip or uv. Ensure you also install the desired LLM provider SDK as an Instructor extra.

```bash
pip install atomic-agents
```

```bash
uv add atomic-agents
```

```bash
pip install instructor[groq]        # for Groq
pip install instructor[anthropic]   # for Anthropic
pip install instructor[google-genai] # for Gemini
```

--------------------------------

### Groq Provider Setup

Source: https://github.com/eigenwise/atomic-agents/blob/main/claude-plugin/atomic-agents/skills/framework/references/providers.md

Initialize the instructor client for Groq. Set the model and API parameters. Use Mode.JSON as tool-calling is not supported for all Groq models.

```python
import os, instructor
from groq import Groq
from instructor import Mode

client = instructor.from_groq(Groq(api_key=os.environ["GROQ_API_KEY"])), mode=Mode.JSON)
model = "llama-3.3-70b-versatile"
api_params = {"max_tokens": 2048}
# In AgentConfig: mode=Mode.JSON
```

--------------------------------

### OpenAI Provider Setup

Source: https://github.com/eigenwise/atomic-agents/blob/main/claude-plugin/atomic-agents/skills/framework/references/providers.md

Initialize the instructor client for OpenAI. Set the model and API parameters. Reasoning models may require specific configurations.

```python
import os, instructor
from openai import OpenAI
from instructor import Mode

client = instructor.from_openai(OpenAI(api_key=os.environ["OPENAI_API_KEY"]))
model = "gpt-5-mini"   # also: "gpt-5", "gpt-5-nano", and reasoning variants
api_params = {"reasoning_effort": "low", "max_tokens": 2048}
```

--------------------------------

### Install Dependencies

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/basic-multimodal/README.md

Install project dependencies using the 'uv' package manager.

```bash
uv sync
```

--------------------------------

### Set up SearxNG with Docker

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/web-search-agent/README.md

Instructions to set up a local SearXNG instance using Docker. This includes creating a directory, pulling the Docker image, and running the container with specified ports and volumes.

```bash
mkdir my-instance
cd my-instance
export PORT=8080
docker pull searxng/searxng
docker run --rm \
           -d -p ${PORT}:8080 \
           -v "${PWD}/searxng:/etc/searxng" \
           -e "BASE_URL=http://localhost:$PORT/" \
           -e "INSTANCE_NAME=my-instance" \
           searxng/searxng
```

--------------------------------

### Install atomic-agents Package

Source: https://github.com/eigenwise/atomic-agents/blob/main/agents.md

Install the core atomic-agents Python package using pip.

```bash
pip install atomic-agents
```

--------------------------------

### Ollama (Local) Provider Setup

Source: https://github.com/eigenwise/atomic-agents/blob/main/claude-plugin/atomic-agents/skills/framework/references/providers.md

Initialize the instructor client for Ollama running locally. No API key is needed. Use Mode.JSON as Ollama's OpenAI adapter does not reliably implement tool-calling.

```python
import instructor
from openai import OpenAI
from instructor import Mode

client = instructor.from_openai(
    OpenAI(base_url="http://localhost:11434/v1", api_key="ollama"),
    mode=Mode.JSON,
)
model = "llama3.1"      # any model pulled with `ollama pull`
api_params = {"max_tokens": 2048}
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/mcp-agent/example-mcp-server/README.md

Change the current directory to the example MCP server project.

```bash
cd atomic-examples/mcp-agent/example-mcp-server
```

--------------------------------

### Install Atomic Agents Dependencies

Source: https://github.com/eigenwise/atomic-agents/blob/main/agents.md

Clone the repository and install all workspace packages using uv.

```bash
git clone https://github.com/eigenwise/atomic-agents.git
cd atomic-monorepo

uv sync

uv sync --all-packages
```

--------------------------------

### Run Application Main Entry Point

Source: https://github.com/eigenwise/atomic-agents/blob/main/claude-plugin/atomic-agents/skills/new-app/SKILL.md

Use this command to run the main entry point of the application after setting up the environment and API key.

```bash
uv run python -m <project_name>.main
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/progressive-disclosure/README.md

Clone the atomic-agents repository and install project dependencies using uv.

```bash
git clone https://github.com/eigenwise/atomic-agents
cd atomic-agents/atomic-examples/progressive-disclosure

uv sync
```

--------------------------------

### Run MCP Client (Direct SSE)

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/examples/mcp_agent.md

Navigates to the example-client directory and directly runs the SSE client.

```bash
cd example-client
uv run python -m example_client.main_sse
```

--------------------------------

### Initialize and Run AtomicAgent

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/api/agents.md

Demonstrates how to initialize an AtomicAgent with basic configuration and run it with user input. Also shows how to stream responses asynchronously.

```python
from atomic_agents import AtomicAgent, AgentConfig
from atomic_agents.context import ChatHistory, SystemPromptGenerator

# Create agent with basic configuration
agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](
    config=AgentConfig(
        client=instructor.from_openai(OpenAI()),
        model="gpt-4-turbo-preview",
        history=ChatHistory(),
        system_prompt_generator=SystemPromptGenerator()
    )
)

# Run the agent
response = agent.run(user_input)

# Stream responses
async for partial_response in agent.run_async(user_input):
    print(partial_response)
```

--------------------------------

### Run MCP Client (Direct STDIO)

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/examples/mcp_agent.md

Navigates to the example-client directory and directly runs the STDIO client.

```bash
cd example-client
uv run python -m example_client.main_stdio
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/eigenwise/atomic-agents/blob/main/guides/DEV_GUIDE.md

Installs the uv package manager. Choose the script appropriate for your operating system.

```bash
# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```powershell
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Configure Atomic Agent with Groq client

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/guides/faq.md

Initialize an Instructor client for Groq. Use instructor.Mode.JSON for structured output. Ensure the 'groq' extra is installed.

```python
import instructor
from groq import Groq

client = instructor.from_groq(Groq(), mode=instructor.Mode.JSON)
```

--------------------------------

### Install LLM provider extras

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/guides/faq.md

Install additional packages for specific LLM providers like Anthropic, Groq, or Gemini.

```bash
# For Anthropic
pip install instructor[anthropic]

# For Groq
pip install instructor[groq]

# For Gemini
pip install instructor[google-genai]
```

--------------------------------

### Use BoCha Search Tool

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-forge/tools/bocha_search/README.md

Example of initializing and running the BoCha Search Tool with specific queries. Ensure the BOCHA_API_KEY environment variable is set.

```python
import os
from tool.bocha_search import BoChaSearchTool, BoChaSearchToolConfig, BoChaSearchToolInputSchema

# Initialize the tool with your BoCha instance URL
config = BoChaSearchToolConfig(api_key=os.getenv("BOCHA_API_KEY"), count=5)
search_tool = BoChaSearchTool(config=config)

# Define input data
input_data = BoChaSearchToolInputSchema(
    queries=["Python programming", "Machine learning"],
)

# Perform the search
result = search_tool.run(input_data)
print(result)
```

--------------------------------

### Run MCP Client (Transport Selection)

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/examples/mcp_agent.md

Navigates to the example-client directory and runs the main client launcher, allowing transport selection via arguments.

```bash
cd example-client
uv run python -m example_client.main --transport sse
```

--------------------------------

### Validate Plugin Installation

Source: https://github.com/eigenwise/atomic-agents/blob/main/claude-plugin/atomic-agents/README.md

Run this command to validate your plugin installation. This helps ensure the plugin is correctly set up and functional.

```bash
/plugin validate /path/to/claude-plugin/atomic-agents
```

--------------------------------

### Tavily Search Tool Usage Example

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-forge/tools/tavily_search/README.md

An example demonstrating how to initialize and use the Tavily Search Tool to perform searches.

```APIDOC
## Usage

Here's an example of how to use the Tavily Search Tool:


```python
import os
from tool.tavily_search import TavilyTool, TavilySearchToolConfig

# Initialize the tool with your Tavily instance URL
config = TavilySearchToolConfig(api_key=os.getenv("TAVILY_API_KEY"), max_results=5)
search_tool = TavilyTool(config=config)

# Define input data
input_data = TavilyTool.input_schema(
    queries=["Python programming", "Machine learning"],
)

# Perform the search
result = search_tool.run(input_data)
print(result)
```
```

--------------------------------

### Set Up Environment Variables

Source: https://github.com/eigenwise/atomic-agents/blob/main/atomic-examples/basic-multimodal/README.md

Create a .env file to store your OpenAI API key. Replace 'your_openai_api_key' with your actual key.

```env
OPENAI_API_KEY=your_openai_api_key
```

--------------------------------

### Python Client Setup for Multiple AI Providers

Source: https://github.com/eigenwise/atomic-agents/blob/main/docs/guides/quickstart.md

Python code demonstrating how to set up clients for different AI providers using Instructor. It includes environment variable loading, chat history initialization, and a function to dynamically configure the client based on user input.

```python
import os
import instructor
from rich.console import Console
from rich.text import Text
from atomic_agents.context import ChatHistory
from atomic_agents import AtomicAgent, AgentConfig, BasicChatInputSchema, BasicChatOutputSchema
from dotenv import load_dotenv

load_dotenv()

# Initialize console for pretty outputs
console = Console()

# History setup
history = ChatHistory()

# Initialize history with an initial message from the assistant
initial_message = BasicChatOutputSchema(chat_message="Hello! How can I assist you today?")
history.add_message("assistant", initial_message)

# Function to set up the client based on the chosen provider
def setup_client(provider):
    if provider == "openai":
        from openai import OpenAI
        api_key = os.getenv("OPENAI_API_KEY")
        client = instructor.from_openai(OpenAI(api_key=api_key))
        model = "gpt-5-mini"

    elif provider == "anthropic":
        from anthropic import Anthropic
        api_key = os.getenv("ANTHROPIC_API_KEY")
        client = instructor.from_anthropic(Anthropic(api_key=api_key))
        model = "claude-3-5-haiku-20241022"

    elif provider == "groq":
        from groq import Groq
        api_key = os.getenv("GROQ_API_KEY")
        client = instructor.from_groq(
            Groq(api_key=api_key),
            mode=instructor.Mode.JSON
        )
        model = "mixtral-8x7b-32768"

    elif provider == "ollama":
        from openai import OpenAI as OllamaClient
        client = instructor.from_openai(
            OllamaClient(
                base_url="http://localhost:11434/v1",
                api_key="ollama"
            ),
            mode=instructor.Mode.JSON
        )
        model = "llama3"

    elif provider == "gemini":
        from openai import OpenAI
        api_key = os.getenv("GEMINI_API_KEY")
        client = instructor.from_openai(
            OpenAI(
                api_key=api_key,
                base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
            ),
            mode=instructor.Mode.JSON
        )
        model = "gemini-2.0-flash-exp"
        
    elif provider == "openrouter":
        from openai import OpenAI as OpenRouterClient
        api_key = os.getenv("OPENROUTER_API_KEY")
        client = instructor.from_openai(
            OpenRouterClient(
                base_url="https://openrouter.ai/api/v1",
                api_key=api_key
            )
        )
        model = "mistral/ministral-8b"

    else:
        raise ValueError(f"Unsupported provider: {provider}")

    return client, model

# Prompt for provider choice
provider = console.input("Choose a provider (openai/anthropic/groq/ollama/gemini/openrouter): ").lower()

# Set up client and model
client, model = setup_client(provider)

# Create agent with chosen provider
agent = AtomicAgent[BasicChatInputSchema, BasicChatOutputSchema](
    config=AgentConfig(
        client=client,
        model=model,
        history=history,
        model_api_parameters={"max_tokens": 2048}
    )
)
```