Skip to main content

​
YAML Configuration

# config.agent.yaml
tools:
  external_tools:
    # Single API endpoint
    - tag: "@api/GET/https://api.github.com/users/{username}"
      name: "get_github_user"

    # Multiple endpoints with mapping
    - tag: "@api/https://jsonplaceholder.typicode.com"
      name: "jsonplaceholder_api"
      map:
        get_posts: "GET/posts"
        get_post: "GET/posts/{id}"
        create_post: "POST/posts"
        update_post: "PUT/posts/{id}"
        delete_post: "DELETE/posts/{id}"

    # API with custom headers
    - tag: "@api/GET/https://api.example.com/protected"
      name: "protected_api"
      headers:
        Authorization: "Bearer ${API_TOKEN}"
        Content-Type: "application/json"

​
Python Usage

from nomos import AgentConfig
from nomos.config import ToolsConfig, ExternalTool

config = AgentConfig(
    name="api_agent",
    tools=ToolsConfig(
        external_tools=[
            ExternalTool(
                tag="@api/GET/https://api.github.com/users/{username}",
                name="get_github_user"
            ),
            ExternalTool(
                tag="@api/https://jsonplaceholder.typicode.com",
                name="posts_api",
                map={
                    "get_posts": "GET/posts",
                    "create_post": "POST/posts"
                }
            )
        ]
    ),
    # ... other config
)

​
API Tool Features

URL Parameters

Support for dynamic URL parameters like {username} and {id}

HTTP Methods

Support for GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS

Query Parameters

Automatic handling of query parameters passed as tool arguments

Request Bodies

Support for JSON request bodies via the body parameter

Custom Headers

Support for authentication and custom headers

Error Handling

Automatic HTTP error handling with proper status codes

​
API Tool Examples

# Weather API example
- tag: "@api/GET/https://api.openweathermap.org/data/2.5/weather"
  name: "get_weather"
  headers:
    Authorization: "Bearer ${WEATHER_API_KEY}"

# REST API CRUD operations
- tag: "@api/https://api.example.com/v1"
  name: "user_management"
  map:
    list_users: "GET/users"
    get_user: "GET/users/{id}"
    create_user: "POST/users"
    update_user: "PUT/users/{id}"
    delete_user: "DELETE/users/{id}"
  headers:
    Authorization: "Bearer ${API_TOKEN}"

​
Tool Parameter Definitions

tools:
  external_tools:
    - tag: "@api/GET/https://api.github.com/users/{username}"
      name: "get_github_user"

  tool_defs:
    get_github_user:
      desc: "Get GitHub user information"
      args:
        - key: username
          type: str
          desc: "GitHub username"
        - key: per_page
          type: int
          desc: "Number of results per page"
          default: 30

​
Python Package Tools

NOMOS can directly use functions from Python packages without wrapper code:

​
YAML Configuration

# config.agent.yaml
tools:
  external_tools:
    - tag: "@pkg/itertools.combinations"
      name: "combinations"
    - tag: "@pkg/math.sqrt"
      name: "sqrt"
    - tag: "@pkg/datetime.datetime.now"
      name: "get_current_time"
    - tag: "@pkg/json.loads"
      name: "parse_json"
      kwargs:
        strict: false
    - tag: "@pkg/requests.get"
      name: "http_get"
    - tag: "@pkg/uuid.uuid4"
      name: "generate_uuid"

​
Python Usage

from nomos import AgentConfig
from nomos.config import ToolsConfig, ExternalTool

config = AgentConfig(
    name="utility_agent",
    tools=ToolsConfig(
        external_tools=[
            ExternalTool(tag="@pkg/math.sqrt", name="sqrt"),
            ExternalTool(tag="@pkg/itertools.combinations", name="combinations"),
            ExternalTool(tag="@pkg/datetime.datetime.now", name="get_current_time"),
        ]
    ),
    # ... other config
)
)

​
Benefits

No Wrapper Code

Use any Python function directly without writing wrapper code

Automatic Validation

Function signatures provide automatic parameter validation

Docstring Descriptions

Function docstrings automatically generate tool descriptions

Python Ecosystem

Access to the entire Python package ecosystem

​
CrewAI Tools Integration

Use existing CrewAI tools directly in your NOMOS agents:

​
Available CrewAI Tools

# config.agent.yaml
tools:
  external_tools:
    - tag: "@crewai/FileReadTool"
      name: "file_read_tool"
    - tag: "@crewai/FileWriteTool"
      name: "file_write_tool"
    - tag: "@crewai/DirectoryReadTool"
      name: "directory_read_tool"
    - tag: "@crewai/CodeDocsSearchTool"
      name: "code_search_tool"
      kwargs:
        docs_url: "https://docs.example.com"
    - tag: "@crewai/WebsiteSearchTool"
      name: "website_search"
      kwargs:
        website: "https://example.com"
    - tag: "@crewai/SerperDevTool"
      name: "web_search"
    - tag: "@crewai/YoutubeChannelSearchTool"
      name: "youtube_search"
      kwargs:
        youtube_channel_handle: "@channelname"

​
Python Usage

from nomos import AgentConfig
from nomos.config import ToolsConfig, ExternalTool

# These can be used directly in NOMOS
config = AgentConfig(
    name="research_agent",
    tools=ToolsConfig(
        external_tools=[
            ExternalTool(tag="@crewai/FileReadTool", name="read_file"),
            ExternalTool(tag="@crewai/WebsiteSearchTool", name="web_search",
                        kwargs={"website": "https://example.com"}),
            ExternalTool(tag="@crewai/SerperDevTool", name="search_web")
        ]
    ),
    # ... other config
)
)

​
CrewAI Tool Examples

# Example of using CrewAI tools in steps
steps = [
    Step(
        step_id="research",
        description="Research information using web search and file reading",
        available_tools=["web_search", "read_file", "website_search"],
        routes=[
            Route(target="analysis", condition="Research complete")
        ]
    )
]

​
LangChain Tools Integration

Integrate LangChain tools seamlessly: 
# config.agent.yaml
tools:
  external_tools:
    - tag: "@langchain/DuckDuckGoSearchRun"
      name: "web_search"
    - tag: "@langchain/ShellTool"
      name: "shell_command"
    - tag: "@langchain/PythonREPLTool"
      name: "python_repl"
    - tag: "@langchain/WikipediaQueryRun"
      name: "wikipedia_search"
      kwargs:
        top_k_results: 3
    - tag: "@langchain/ArxivQueryRun"
      name: "arxiv_search"
    - tag: "@langchain/GoogleSearchAPIWrapper"
      name: "google_search"
    - tag: "@langchain/BingSearchAPIWrapper"
      name: "bing_search"

​
Python Usage

from nomos import AgentConfig
from nomos.config import ToolsConfig, ExternalTool

# Direct integration in Python
config = AgentConfig(
    name="research_assistant",
    tools=ToolsConfig(
        external_tools=[
            ExternalTool(tag="@langchain/DuckDuckGoSearchRun", name="search"),
            ExternalTool(tag="@langchain/ShellTool", name="shell"),
            ExternalTool(tag="@langchain/WikipediaQueryRun", name="wiki_search",
                        kwargs={"top_k_results": 3})
        ]
    ),
    # ... other config
)
)

​
LangChain Tool Configuration

# Advanced LangChain tool configuration
tools:
  external_tools:
    - tag: "@langchain/GoogleSearchAPIWrapper"
      name: "google_search"
      kwargs:
        google_api_key: "${GOOGLE_API_KEY}"
        google_cse_id: "${GOOGLE_CSE_ID}"
        k: 5

    - tag: "@langchain/SQLDatabaseToolkit"
      name: "sql_toolkit"
      kwargs:
        db_uri: "postgresql://user:pass@localhost/db"
        include_tables: ["users", "orders", "products"]

​
Tool Integration Examples

​
Research Agent with Multiple Tool Types

name: research_agent
persona: "Expert researcher with access to multiple information sources"

steps:
  - step_id: gather_info
    description: "Gather information from multiple sources"
    available_tools:
      - web_search          # LangChain DuckDuckGo
      - wikipedia_search    # LangChain Wikipedia
      - read_file          # CrewAI FileReadTool
      - parse_json         # Python json.loads
      - combinations       # Python itertools.combinations
    routes:
      - target: analyze_data
        condition: "Sufficient information gathered"

tools:
  external_tools:
    # LangChain tools
    - tag: "@langchain/DuckDuckGoSearchRun"
      name: "web_search"
    - tag: "@langchain/WikipediaQueryRun"
      name: "wikipedia_search"
      kwargs:
        top_k_results: 5

    # CrewAI tools
    - tag: "@crewai/FileReadTool"
      name: "read_file"

    # Python package functions
    - tag: "@pkg/json.loads"
      name: "parse_json"
    - tag: "@pkg/itertools.combinations"
      name: "combinations"

​
Data Analysis Agent

name: data_analyst
persona: "Data analyst with file processing and calculation capabilities"

steps:
  - step_id: load_data
    description: "Load and process data files"
    available_tools:
      - read_file          # CrewAI
      - parse_json         # Python
      - sqrt              # Python math
      - python_repl       # LangChain
    routes:
      - target: analysis
        condition: "Data loaded successfully"

tools:
  external_tools:
    # File operations
    - tag: "@crewai/FileReadTool"
      name: "read_file"
    - tag: "@crewai/DirectoryReadTool"
      name: "list_directory"

    # Data processing
    - tag: "@pkg/json.loads"
      name: "parse_json"
    - tag: "@pkg/csv.reader"
      name: "read_csv"
    - tag: "@pkg/math.sqrt"
      name: "sqrt"

    # Code execution
    - tag: "@langchain/PythonREPLTool"
      name: "python_repl"
Follow the respective documentation for each tool source to set up your environment

​
Troubleshooting

​
Common Issues

Problem: External tool not loadingSolutions:
  • Verify the package is installed: pip install package-name
  • Check the tool tag format: @provider/ToolName
  • Ensure the tool class exists in the package
Problem: Module import failuresSolutions:
  • Install missing dependencies
  • Check Python environment
  • Verify package versions compatibility
Problem: Tool configuration not workingSolutions:
  • Check YAML syntax
  • Verify environment variables
  • Review tool documentation for required parameters

​
Next Steps

Tools Introduction

Learn the basics of tools and how to create your own

Security & Best Practices

Implement secure tool usage and validation
External tool integration makes NOMOS incredibly powerful by giving you access to the entire ecosystem of existing tools while maintaining the structure and auditability that makes NOMOS unique.