### Navigate to quickstart directory

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Change the current working directory to the quickstart examples folder.

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

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

### Run Atomic Agents Examples

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Command to execute an example script from the quickstart directory.

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

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

### Set up the client

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Install dependencies for the example client.

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

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

### Set up the server

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Install dependencies for the example MCP server.

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

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

### Install all workspace packages

Source: https://eigenwise.github.io/atomic-agents/contributing.html

Install all workspace packages, including examples and tools, using uv.

```bash
uv sync --all-packages

```

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

### Package Initialization and Quick Start

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

The __init__.py file exports core components and provides a quick start example for using DSPyAtomicModule.

```python
"""
DSPy + Atomic Agents Integration Package.

This package demonstrates how to combine DSPy's automatic prompt optimization
with Atomic Agents' type-safe structured outputs.

Package Structure:
    domain/      - Core business logic (models, datasets, evaluation)
    stages/      - Demonstration stages (dspy, atomic, combined)
    presentation/ - UI layer (Rich console output)
    bridge.py    - DSPy ↔ Atomic Agents integration module

Quick Start:
    >>> from dspy_integration import DSPyAtomicModule, MovieReviewInput, MovieGenreOutput
    >>> module = DSPyAtomicModule(
    ...     input_schema=MovieReviewInput,
    ...     output_schema=MovieGenreOutput,
    ...     use_chain_of_thought=True,
    ... )
    >>> result = module.run_validated(review="Amazing action movie!")
    >>> print(result.genre)  # Type-safe output!

Run Demo:
    uv run python -m dspy_integration.main
"""

# Domain exports
from dspy_integration.domain.models import (
    GENRES,
    GenreType,
    MovieGenreOutput,
    MovieReviewInput,
    EvalResult,
)
from dspy_integration.domain.datasets import TRAINING_DATASET, TEST_DATASET
from dspy_integration.domain.evaluation import evaluate_predictions

# Bridge exports
from dspy_integration.bridge import (
    DSPyAtomicModule,
    DSPyAtomicPipeline,
    create_dspy_example,
    create_dspy_signature_from_schemas,
    pydantic_to_dspy_fields,
)

# Original schemas (for backwards compatibility)
from dspy_integration.schemas import (
    SentimentInputSchema,
    SentimentOutputSchema,
    QuestionInputSchema,
    AnswerOutputSchema,
    SummaryInputSchema,
    SummaryOutputSchema,
)

# Stage exports (for advanced usage)
from dspy_integration.stages import (
    run_stage1_raw_dspy,
    run_stage2_raw_atomic_agents,
    run_stage3_combined,
)

__version__ = "0.1.0"

__all__ = [
    # Version
    "__version__",
    # Domain - Types
    "GENRES",
    "GenreType",
    # Domain - Schemas (new)
    "MovieGenreOutput",
    "MovieReviewInput",
    # Domain - Data structures
    "EvalResult",
    # Domain - Datasets
    "TRAINING_DATASET",
    "TEST_DATASET",
    # Domain - Evaluation
    "evaluate_predictions",
    # Bridge - Core classes
    "DSPyAtomicModule",
    "DSPyAtomicPipeline",
    # Bridge - Utilities
    "create_dspy_example",
    "create_dspy_signature_from_schemas",
    "pydantic_to_dspy_fields",
    # Original schemas (backwards compatibility)
    "SentimentInputSchema",
    "SentimentOutputSchema",
    "QuestionInputSchema",
    "AnswerOutputSchema",
    "SummaryInputSchema",
    "SummaryOutputSchema",
    # Stages - Runners
    "run_stage1_raw_dspy",
    "run_stage2_raw_atomic_agents",
    "run_stage3_combined",
]
```

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

### Navigate to the nested-multimodal directory

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Change into the example directory to begin setup.

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

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

### Run the DSPy integration example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Commands to navigate to the example directory, install dependencies, set the OpenAI API key, and execute the main script.

```bash
# Navigate to the example directory
cd atomic-examples/dspy-integration

# Install dependencies
uv sync

# Set your OpenAI API key (or create a .env file)
export OPENAI_API_KEY="your-key-here"

# Run the full didactic example
uv run python -m dspy_integration.main
```

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

### Example Usage Boilerplate

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Standard setup for running the example, including environment loading and console initialization.

```python
if __name__ == "__main__":
    import os
    from dotenv import load_dotenv
    from rich.console import Console
    import openai
    from progressive_disclosure.registry.tool_registry import ToolMetadata

    load_dotenv()
    console = Console()
```

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

### Navigate to Example Directory

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Change the working directory to the persistent memory example folder.

```bash
cd atomic-agents/atomic-examples/persistent-memory
```

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

### Run the hooks example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Execute the main script for the hooks example using uv.

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

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

### Run the nested multimodal example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Execute the main Python script for the example.

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

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

### Run the Multimodal Example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

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

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

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

### Run Phoenix Tracing Example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Commands to sync dependencies and execute the tracing example script.

```bash
uv sync
uv run python phoenix_tracing/main.py
```

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

### Run basic chatbot example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Execute the basic chatbot example script using uv.

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

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

### Install Atomic Agents via uv

Source: https://eigenwise.github.io/atomic-agents/_sources/guides/faq.md.txt

Recommended installation command using uv.

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

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

### SearXNGSearchTool usage example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Example of initializing the SearXNGSearchTool and executing a search query using the input schema.

```python
if __name__ == "__main__":
    from rich.console import Console
    from dotenv import load_dotenv

    load_dotenv()
    rich_console = Console()

    search_tool_instance = SearXNGSearchTool(config=SearXNGSearchToolConfig(base_url="http://localhost:8080", max_results=5))

    search_input = SearXNGSearchTool.input_schema(
        queries=["Python programming", "Machine learning", "Artificial intelligence"],
        category="news",
    )

    output = search_tool_instance.run(search_input)

    rich_console.print(output)
```

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

### Observability Setup with Manual OpenTelemetry

Source: https://eigenwise.github.io/atomic-agents/_downloads/5c23f43b6ba11dcb38af1b9d10195c52/llms-docs.txt

Installation for manual OpenTelemetry setup without Phoenix.

```APIDOC
## Install

### Description
Install the required packages for manual OpenTelemetry tracing.

### Command
pip install "atomic-agents[observability]" opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

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

### Observability Setup with Phoenix

Source: https://eigenwise.github.io/atomic-agents/_downloads/5c23f43b6ba11dcb38af1b9d10195c52/llms-docs.txt

Installation and automatic setup for tracing Atomic Agents with Arize Phoenix using OpenTelemetry.

```APIDOC
## Install

### Description
Install the required packages for observability with Phoenix.

### Command
pip install "atomic-agents[observability]" arize-phoenix-otel openinference-instrumentation-openai

## Setup with Phoenix (automatic)

### Description
Register the tracer provider with auto-instrumentation to automatically trace agent and tool runs.

### Code Example
from phoenix.otel import register

tracer_provider = register(project_name="my-app", auto_instrument=True)
```

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

### Install Instructor provider SDKs

Source: https://eigenwise.github.io/atomic-agents/_sources/index.md.txt

Install specific provider SDKs as instructor extras to enable support for Groq, Anthropic, or Gemini.

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

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

### Install Observability Dependencies

Source: https://eigenwise.github.io/atomic-agents/_downloads/5c23f43b6ba11dcb38af1b9d10195c52/llms-docs.txt

Commands to install the necessary packages for observability. Use the first command for Phoenix and the second for manual OpenTelemetry setup.

```bash
pip install "atomic-agents[observability]" arize-phoenix-otel openinference-instrumentation-openai
```

```bash
pip install "atomic-agents[observability]" opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

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

### Test setup_client with provider number '7'

Source: https://eigenwise.github.io/atomic-agents/_downloads/4057bccd805136268a3adbcbd7512c17/llms-source.txt

Verifies the pattern for initializing an instructor client with a Minimax base URL and API key.

```python
def test_setup_client_minimax_by_number(self):
        """Test setup_client with provider number '7'."""
        import sys

        sys.path.insert(
            0,
            os.path.join(
                os.path.dirname(__file__),
                "..",
                "..",
                "..",
                "atomic-examples",
                "quickstart",
                "quickstart",
            ),
        )
        # We can't import the example directly (it has top-level console input),
        # but we can verify the pattern works
        from openai import OpenAI

        api_key = "test-minimax-key"
        raw_client = OpenAI(base_url="https://api.minimax.io/v1", api_key=api_key)
        client = instructor.from_openai(raw_client)
        assert isinstance(client, instructor.Instructor)
```

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

### Configure Groq client

Source: https://eigenwise.github.io/atomic-agents/_sources/guides/faq.md.txt

Initialize an instructor client for Groq.

```python
import instructor
from groq import Groq

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

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

### Example usage of search and list tools

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Demonstrates how to create a registry, register tools, and execute search and list operations.

```python
if __name__ == "__main__":
    from progressive_disclosure.registry.tool_registry import ToolMetadata

    # Create a test registry
    registry = ToolRegistry()
    registry.register(
        ToolMetadata(
            name="AddNumbers",
            description="Add two numbers together",
            keywords=["add", "sum", "plus", "arithmetic"],
            category="math",
        )
    )
    registry.register(
        ToolMetadata(
            name="SubtractNumbers",
            description="Subtract one number from another",
            keywords=["subtract", "minus", "difference", "arithmetic"],
            category="math",
        )
    )
    registry.register(
        ToolMetadata(
            name="SearchWeb",
            description="Search the web for information",
            keywords=["search", "web", "query", "find"],
            category="search",
        )
    )

    # Test search
    search_tool = SearchToolsTool(SearchToolsConfig(registry=registry))
    result = search_tool.run(SearchToolsInputSchema(search_query="add numbers math"))
    print("Search results:")
    print(f"  Matched: {result.matched_tools}")
    print(f"  Descriptions: {result.tool_descriptions}")

    # Test list all
    list_tool = ListAllToolsTool(SearchToolsConfig(registry=registry))
    all_result = list_tool.run(ListAllToolsInputSchema())
    print(f"\nAll tools ({all_result.total_count}):")
    for tool in all_result.tools:
        print(f"  - {tool['name']}: {tool['description']}")
```

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

### Install observability dependencies for manual OpenTelemetry setup

Source: https://eigenwise.github.io/atomic-agents/_sources/guides/observability.md.txt

Installs the Atomic Agents observability extra along with the OpenTelemetry SDK and OTLP HTTP exporter for manual configuration.

```bash
pip install "atomic-agents[observability]" opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

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

### Run PDF Analysis Example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Execute the main Python script to start the analysis.

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

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

### Initialize and Run Async MCP STDIO Client

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

This snippet demonstrates setting up an MCP client via STDIO, initializing a session, and dynamically building an action schema from discovered tools, resources, and prompts.

```python
# Command to run the STDIO server.
    # In practice, this could be something like "pipx some-other-persons-server or npx some-other-persons-server
    # if working with a server you did not write yourself.
    mcp_stdio_server_command: str = "uv run example-mcp-server --mode stdio"

    def __post_init__(self):
        if not self.openai_api_key:
            raise ValueError("OPENAI_API_KEY environment variable is not set")


config = MCPConfig()
console = Console()
client = instructor.from_openai(openai.OpenAI(api_key=config.openai_api_key))


class FinalResponseSchema(BaseIOSchema):
    """Schema for providing a final text response to the user."""

    response_text: str = Field(..., description="The final text response to the user's query")


async def main():
    async with AsyncExitStack() as stack:
        # Start MCP server
        cmd, *args = shlex.split(config.mcp_stdio_server_command)
        read_stream, write_stream = await stack.enter_async_context(
            stdio_client(StdioServerParameters(command=cmd, args=args))
        )
        session = await stack.enter_async_context(ClientSession(read_stream, write_stream))
        await session.initialize()

        # Fetch tools, resources and prompts - factory sees running loop
        tools = await fetch_mcp_tools_async(
            transport_type=MCPTransportType.STDIO,
            client_session=session,  # factory sees running loop
        )
        resources = await fetch_mcp_resources_async(
            transport_type=MCPTransportType.STDIO,
            client_session=session,
        )
        prompts = await fetch_mcp_prompts_async(
            transport_type=MCPTransportType.STDIO,
            client_session=session,
        )

        if not tools and not resources and not prompts:
            raise RuntimeError(
                "No MCP tools or resources or prompts found. Please ensure the MCP server is running and accessible."
            )

        # Build mapping from input_schema to ToolClass
        tool_schema_to_class_map: Dict[Type[BaseIOSchema], Type[AtomicAgent]] = {
            ToolClass.input_schema: ToolClass for ToolClass in tools if hasattr(ToolClass, "input_schema")
        }
        # Collect all tool input schemas
        tool_input_schemas = tuple(tool_schema_to_class_map.keys())

        # Build mapping for resources and prompts
        resource_schema_to_class_map: Dict[Type[BaseIOSchema], Any] = {  # type: ignore
            ResourceClass.input_schema: ResourceClass for ResourceClass in resources if hasattr(ResourceClass, "input_schema")
        }
        resource_input_schemas = tuple(resource_schema_to_class_map.keys())

        prompt_schema_to_class_map: Dict[Type[BaseIOSchema], Any] = {  # type: ignore
            PromptClass.input_schema: PromptClass for PromptClass in prompts if hasattr(PromptClass, "input_schema")
        }
        prompt_input_schemas = tuple(prompt_schema_to_class_map.keys())

        # Available schemas include all tool input schemas, resource schemas, prompts and the final response schema
        available_schemas = tool_input_schemas + resource_input_schemas + prompt_input_schemas + (FinalResponseSchema,)

        # Define the Union of all action schemas
        ActionUnion = Union[available_schemas]

        # 2. Schema and class definitions
        class MCPOrchestratorInputSchema(BaseIOSchema):
            """Input schema for the MCP Orchestrator Agent."""

            query: str = Field(..., description="The user's query to analyze.")

        class OrchestratorOutputSchema(BaseIOSchema):
            """Output schema for the orchestrator. Contains reasoning and the chosen action."""

            reasoning: str = Field(
                ..., description="Detailed explanation of why this action was chosen and how it will address the user's query."
            )
            action: ActionUnion = Field(  # type: ignore
                ...,
                description="The chosen action: either a tool/resource/prompt's input schema instance or a final response schema instance.",
            )

            model_config = {"arbitrary_types_allowed": True}

        # 3. Main logic
        console.print("[bold green]Initializing MCP Agent System (STDIO mode - Async)...[/bold green]")

        # Display available tools
        table = Table(title="Available MCP Tools", box=None)
        table.add_column("Tool Name", style="cyan")
        table.add_column("Input Schema", style="yellow")
        table.add_column("Description", style="magenta")
        for ToolClass in tools:
            schema_name = ToolClass.input_schema.__name__ if hasattr(ToolClass, "input_schema") else "N/A"
            table.add_row(ToolClass.mcp_tool_name, schema_name, ToolClass.__doc__ or "")
        console.print(table)
```

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

### Project Configuration pyproject.toml

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

The project configuration file defining dependencies and build settings for the quickstart examples.

```toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["quickstart"]

[project]
name = "quickstart"
version = "1.0.0"
description = "Quickstart example for Atomic Agents"
readme = "README.md"
authors = [
    { name = "Kenny Vaneetvelde", email = "kenny.vaneetvelde@gmail.com" }
]
requires-python = ">=3.12"
dependencies = [
    "atomic-agents",
    "instructor[anthropic,groq,google-genai]==1.14.5",
    "openai>=2.0.0,<3.0.0",
    "python-dotenv>=1.0.1,<2.0.0",
]

[tool.uv.sources]
atomic-agents = { workspace = true }
```

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

### Run Persistent Memory Example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Execute the main script to start the agent and persist conversation history to a SQLite database.

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

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

### Tool Finder Agent Usage Example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Demonstrates how to initialize the ToolRegistry, configure the agent with an OpenAI client, and execute a query to find relevant tools.

```python
>>> registry = ToolRegistry()
>>> registry.register_from_mcp(mcp_definitions)
>>> client = instructor.from_openai(openai.OpenAI())
>>> agent, _, _ = create_tool_finder_agent(registry, client)
>>> result = run_tool_finder(agent, None, None, "Calculate 2+2")
>>> print(result.selected_tools)
['add_numbers']
```

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

### Initialize FastMCP Server with SSE Transport

Source: https://eigenwise.github.io/atomic-agents/_sources/examples/mcp_agent.md.txt

Example setup for an MCP server using FastMCP, registering tools and resources, and creating a Starlette application with CORS support.

```python
# Initialize FastMCP server
mcp = FastMCP("example-mcp-server")

# Register tools and resources
tool_service.register_tools(get_available_tools())
resource_service.register_resources(get_available_resources())

# Create Starlette app with CORS support
app = create_starlette_app(mcp_server)
```

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

### Implement Comprehensive Agent Logging with Hooks

Source: https://eigenwise.github.io/atomic-agents/_sources/guides/logging.md.txt

This example defines an AgentLogger class that registers hooks for request lifecycle events such as start, completion, error, and parsing issues. It uses a RequestContext dataclass to track state across these hooks and logs events as JSON strings.

```python
import time
import logging
import json
from typing import Any, Optional
from dataclasses import dataclass, field
from atomic_agents import AtomicAgent


logger = logging.getLogger("atomic_agents")


@dataclass
class RequestContext:
    """Tracks request context for logging."""
    request_id: str
    start_time: float
    model: Optional[str] = None
    input_tokens: Optional[int] = None
    output_tokens: Optional[int] = None


class AgentLogger:
    """Comprehensive agent logging using hooks."""

    def __init__(self, agent: AtomicAgent):
        self.agent = agent
        self.current_request: Optional[RequestContext] = None

        # Register hooks
        agent.register_hook("completion:kwargs", self._on_request_start)
        agent.register_hook("completion:response", self._on_request_complete)
        agent.register_hook("completion:error", self._on_request_error)
        agent.register_hook("parse:error", self._on_parse_error)

    def _generate_request_id(self) -> str:
        import uuid
        return str(uuid.uuid4())[:8]

    def _on_request_start(self, **kwargs):
        """Log request start."""
        self.current_request = RequestContext(
            request_id=self._generate_request_id(),
            start_time=time.time(),
            model=kwargs.get("model")
        )

        logger.info(json.dumps({
            "event": "request_start",
            "request_id": self.current_request.request_id,
            "model": self.current_request.model,
            "message_count": len(kwargs.get("messages", []))
        }))

    def _on_request_complete(self, response, **kwargs):
        """Log successful request."""
        if not self.current_request:
            return

        duration = time.time() - self.current_request.start_time

        log_data = {
            "event": "request_complete",
            "request_id": self.current_request.request_id,
            "duration_ms": round(duration * 1000, 2),
            "model": self.current_request.model
        }

        # Add token usage if available
        if hasattr(response, "usage"):
            log_data["tokens"] = {
                "prompt": response.usage.prompt_tokens,
                "completion": response.usage.completion_tokens,
                "total": response.usage.total_tokens
            }

        logger.info(json.dumps(log_data))
        self.current_request = None

    def _on_request_error(self, error, **kwargs):
        """Log request error."""
        log_data = {
            "event": "request_error",
            "error_type": type(error).__name__,
            "error_message": str(error)
        }

        if self.current_request:
            log_data["request_id"] = self.current_request.request_id
            log_data["duration_ms"] = round(
                (time.time() - self.current_request.start_time) * 1000, 2
            )

        logger.error(json.dumps(log_data))
        self.current_request = None

    def _on_parse_error(self, error):
        """Log validation error."""
        logger.warning(json.dumps({
            "event": "parse_error",
            "request_id": self.current_request.request_id if self.current_request else None,
            "error_type": type(error).__name__,
            "error_message": str(error)
        }))


# Usage
agent_logger = AgentLogger(agent)
# Logs are automatically created for all agent operations
```

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

### Multi-Provider Agent with Provider Enum and get_client function

Source: https://eigenwise.github.io/atomic-agents/_downloads/5c23f43b6ba11dcb38af1b9d10195c52/llms-docs.txt

Agent setup that can switch between different LLM providers (OpenAI, Anthropic, Groq, Ollama) based on configuration. Defines a Provider enum and a get_client function that returns an instructor client for the specified provider. Requires pip install atomic-agents instructor[anthropic,groq] and API keys for providers to be used.

```python
"""
Multi-Provider Agent Recipe

Agent that can use different LLM providers based on configuration.

Requirements:
- pip install atomic-agents instructor[anthropic,groq]
- Set API keys for providers you want to use
"""

import os
from enum import Enum
from typing import Optional
import instructor
from atomic_agents import AtomicAgent, AgentConfig, BasicChatInputSchema, BasicChatOutputSchema
from atomic_agents.context import ChatHistory


class Provider(Enum):
    OPENAI = "openai"
    ANTHROPIC = "anthropic"
    GROQ = "groq"
    OLLAMA = "ollama"


def get_client(provider: Provider):
    """Get instructor client for specified provider."""
```

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

### Navigate to the hooks-example directory

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Change the current working directory to the hooks-example folder.

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

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

### SearXNG Search Tool Usage Example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Demonstrates how to initialize the SearXNGSearchTool with configuration, define input queries, and execute the search.

```python
if __name__ == "__main__":
    from rich.console import Console
    from dotenv import load_dotenv

    load_dotenv()
    rich_console = Console()

    search_tool_instance = SearXNGSearchTool(
        config=SearXNGSearchToolConfig(base_url=os.getenv("SEARXNG_BASE_URL"), max_results=5)
    )

    search_input = SearXNGSearchTool.input_schema(
        queries=["Python programming", "Machine learning", "Artificial intelligence"],
        category="news",
    )

    output = search_tool_instance.run(search_input)

    rich_console.print(output)
```

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

### Install dependencies with uv

Source: https://eigenwise.github.io/atomic-agents/_sources/contributing.md.txt

Commands to install project dependencies using uv.

```bash
uv sync
```

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

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

### Start the FastAPI server

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Run the FastAPI server using uv.

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

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

### Running Tool Finder Agent Queries

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Shows how to initialize the tool finder agent with a registry and client, then execute queries to identify relevant tools.

```python
# Create client
client = instructor.from_openai(openai.OpenAI(api_key=os.getenv("OPENAI_API_KEY")))

# Create finder agent
agent, _, _ = create_tool_finder_agent(registry, client)

# Test queries
test_queries = [
    "What is 5 plus 3?",
    "Calculate (10 - 4) * 2",
    "Reverse the word HELLO and convert ABC to uppercase",
]

for query in test_queries:
    console.print(f"\n[bold cyan]Query:[/bold cyan] {query}")
    result = run_tool_finder(agent, None, None, query)
    console.print(f"[bold green]Selected tools:[/bold green] {result.selected_tools}")
    console.print(f"[dim]Reasoning: {result.reasoning}[/dim]")
    console.print(f"[dim]Confidence: {result.confidence}[/dim]")

    # Reset history for next query
    agent.history.history = []
    agent.history.current_turn_id = None
```

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

### ToolRegistry Usage Example

Source: https://eigenwise.github.io/atomic-agents/_downloads/4ab0fc6aa1604d4951938115dfe135a5/llms-examples.txt

Demonstrates how to initialize the registry, register tools from MCP definitions, and perform a search.

```python
>>> registry = ToolRegistry()
>>> registry.register_from_mcp(mcp_definitions)
>>> results = registry.search("calculate numbers", max_results=3)
>>> for tool in results:
...     print(f"{tool.name}: {tool.description}")
```

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

### Install Test Dependencies with uv

Source: https://eigenwise.github.io/atomic-agents/_sources/guides/testing.md.txt

Install the required testing packages using uv.

```bash
uv add --dev pytest pytest-asyncio pytest-cov
```