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.

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.

How It Works

---

How to Reference Tools from GitHub

1. Add GitHub URL to tools_sources

   # 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

   roles:
     agent:
       tools:
         - shell_tool
       tasks:
         main:
           description: "Use video tools from GitHub"
   
3. Run Template

   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

   # TEMPLATE.yaml
   requires:
     tools_sources:
       - https://raw.githubusercontent.com/user/repo/main/tools.py
   
3. Run Template

   praisonai templates run ./my-template
   

How to Use Tools via CLI Override

1. Run with Remote Tool Source

   praisonai templates run my-template \
     --tools-source github:MervinPraison/PraisonAI-tools/praisonai_tools
   
2. Run with Multiple Sources

   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

   pip install praisonai-tools
   
2. Add to tools_sources

   # TEMPLATE.yaml
   requires:
     packages:
       - praisonai-tools
     tools_sources:
       - praisonai_tools.video
   
3. Use Tools

   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

   [project]
   name = "my-tools"
   version = "1.0.0"
   
   [project.entry-points."praisonai.tools"]
   my_tools = "my_tools:tools"
   
3. Publish to PyPI

   pip install build twine
   python -m build
   twine upload dist/*
   
4. Use in Templates

   requires:
     packages:
       - my-tools
     tools_sources:
       - my_tools
   

Remote Tool Source Formats

Format	Example
GitHub shorthand	github:user/repo/path
GitHub with branch	github:user/repo/path@branch
Raw URL	https://raw.githubusercontent.com/...
PyPI package	package_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