Skip to main content

Quick Start

Get your External Tool Agent running and start integrating custom tools into NINA workflows.

Prerequisites​

  • Python 3.12 or higher
  • Organization credentials and queue information (provided during agent provisioning)

Installation​

The BEAM agent is distributed as a .whl file provided by Zynap. We recommend installing it in a virtual environment:

# Create and activate a virtual environment
python -m venv beam-env
source beam-env/bin/activate  # On Windows: beam-env\Scripts\activate

# Install the provided .whl file
pip install beam_agent-<version>-py3-none-any.whl

Basic Configuration​

A config.yaml file is provisioned by Zynap with your organization's credentials and queue information. You can safely edit configuration parameters such as agent name, logging, and execution settings — see the Configuration section for details.

Start the Agent​

python my_agent.py

Expected output:

INFO - Starting agent my-agent-01
INFO - Organization: org-abc-123
INFO - Queue backend: sqs
INFO - Storage backend: s3
INFO - Starting queue polling on https://sqs...

Verify It's Working​

  1. Check agent logs - should show "Starting queue polling"
  2. Create a NINA workflow with an External Tool node
  3. Configure the node to use your custom tool name
  4. Execute the workflow
  5. Check agent logs - should show "Processing execution"
  6. Check workflow results in NINA - node should complete successfully

Register Your First Tool​

There are 4 ways to create tools. Here's the simplest using a decorator:

Create my_tools.py:

from beam_agent import beam_tool
from pathlib import Path
from typing import Dict

@beam_tool(name="hello_world", timeout=30)
async def hello_world(input_paths: list, output_path: Path, parameters: Dict) -> Dict:
    """Simple example tool."""
    name = parameters.get('name', 'World')
    return {"message": f"Hello, {name}!"}

Or wrap an existing script (no code changes needed):

from beam_agent import bash_script

# Wraps your script, passes --input and --output automatically
scanner = bash_script("scanner", "/opt/tools/scanner.sh")
agent.register_tool("scanner", scanner)

Update your agent startup:

#!/usr/bin/env python3
import asyncio
from beam_agent import BeamAgent, BeamConfig
import my_tools  # Import to register decorator tools

async def main():
    config = BeamConfig.from_yaml("config.yaml")
    agent = BeamAgent(config)
    await agent.start()

asyncio.run(main())

What's Next​

Common Issues​

Agent not receiving messages?

  • Verify queue URLs in config
  • Check AWS credentials
  • Ensure IAM permissions for SQS

Connection errors?

  • Check network connectivity to AWS
  • Verify security groups allow outbound HTTPS

Tool not found?

  • Ensure tool is imported before starting agent
  • Check tool name matches workflow configuration

See Troubleshooting Guide for detailed solutions.