Praison AI

Remote Tools from GitHub

Step-by-step guide to using tools from GitHub and remote URLs

Pull tool implementations from GitHub URLs and reference them in template manifests.

python
from praisonaiagents import Agent, tool

agent = Agent(name="Remote Tools", instructions="Use tools loaded from remote sources.")
agent.start("Which remote tool sources are configured?")

The user adds tools_sources entries, lists tools in agents.yaml, and runs the template.

Diagram

Remote Tools

📋 tools_sources

🌐 Fetch from GitHub

✅ Usable Tool

How It Works

Diagram
GitHubTemplateUserGitHubTemplateUserRun with a github: tools_sourceFetch the tool implementationTool codeAgent runs with the remote tool

How to Reference Tools from GitHub

  1. Add GitHub URL to tools_sources
    yaml
    # TEMPLATE.yaml
name: my-template
version: "1.0.0"

requires:
  tools_sources:
    - github:MervinPraison/PraisonAI-tools/praisonai_tools/video
  2. Reference Tools in agents.yaml
    yaml
    roles:
  agent:
    tools:
      - shell_tool
    tasks:
      main:
        description: "Use video tools from GitHub"
  3. Run Template
    bash
    praisonai templates run ./my-template

How to Use Tools from Raw GitHub URLs

  1. Get Raw URL

    Navigate to the tools.py file on GitHub and click “Raw” to get the raw URL:

    https://raw.githubusercontent.com/MervinPraison/PraisonAI-tools/main/tools.py
  2. Add to tools_sources
    yaml
    # TEMPLATE.yaml
requires:
  tools_sources:
    - https://raw.githubusercontent.com/user/repo/main/tools.py
  3. Run Template
    bash
    praisonai templates run ./my-template

How to Use Tools via CLI Override

  1. Run with Remote Tool Source
    bash
    praisonai templates run my-template \
  --tools-source github:MervinPraison/PraisonAI-tools/praisonai_tools
  2. Run with Multiple Sources
    bash
    praisonai templates run my-template \
  --tools-source github:user/repo/tools \
  --tools-source ./local_tools.py

How to Install Tools from PyPI

  1. Install Package
    bash
    pip install praisonai-tools
  2. Add to tools_sources
    yaml
    # TEMPLATE.yaml
requires:
  packages:
    - praisonai-tools
  tools_sources:
    - praisonai_tools.video
  3. Use Tools
    bash
    praisonai templates run ./my-template

How to Create Shareable Tool Packages

  1. Create Package Structure
    my-tools/
├── pyproject.toml
├── my_tools/
│   ├── __init__.py
│   └── tools.py
  2. Define pyproject.toml

    The canonical entry-point group is praisonai.tools. The legacy praisonaiagents.tools and praisonai.tool_sources groups are kept as one-cycle deprecated aliases — new tool packages should publish under praisonai.tools.

    toml
    [project]
name = "my-tools"
version = "1.0.0"

[project.entry-points."praisonai.tools"]
my_tools = "my_tools:tools"
  3. Publish to PyPI
    bash
    pip install build twine
python -m build
twine upload dist/*
  4. Use in Templates
    yaml
    requires:
  packages:
    - my-tools
  tools_sources:
    - my_tools

Remote Tool Source Formats

FormatExample
GitHub shorthandgithub:user/repo/path
GitHub with branchgithub:user/repo/path@branch
Raw URLhttps://raw.githubusercontent.com/...
PyPI packagepackage_name.module
Local path./tools.py or ./tools_dir/

Best Practices

Pin a branch or tag for reproducibility

Append @branch to a github: source so a run does not silently change when the upstream repo updates.

Review remote tool code before enabling

Remote tools run in your process. Read the implementation and restrict what it can do before adding it to tools_sources.

Prefer packaged tools for anything shared

Publishing to PyPI and referencing package_name.module gives you versioning and dependency management that raw URLs lack.

Related

Assign Tools to Templates

Wire remote tools into roles

 Debug Tools

Resolve remote tool sources