Configuration

Complete reference for configuring the External Tool Agent.

Configuration File

When you provision an External Tool Agent in NINA, you receive a config.yaml file with your organization's credentials, queue URLs, and storage settings already configured. Do not modify these values.

You can tune performance, polling, and logging settings to match your infrastructure.

Location: Place the file wherever you like — pass the path to BeamConfig.from_yaml("config.yaml")

What You Can Change

These sections are safe to adjust:

Section	What it controls
agent.name	Agent identifier in logs
polling.*	How messages are fetched and processed
execution.*	Timeouts, concurrency, work directory
log_level / log_format	Logging verbosity and format

What You Should NOT Change

These are provisioned by Zynap and must remain as-is:

• agent.organization_id
• agent.encryption_key
• aws.access_key_id / aws.secret_access_key
• aws.work_queue_url / aws.completion_queue_url
• aws.s3_bucket
• aws.region
• queue_backend / storage_backend

Configurable Settings

Polling

Controls how the agent fetches messages from the queue.

polling:
  long_poll_seconds: 20
  max_messages: 4
  visibility_timeout: 300
  visibility_extension_interval: 60

Field	Default	Description
long_poll_seconds	20	How long to wait for messages (max 20)
max_messages	1	Messages fetched per poll (1-10). Set to match max_concurrent_executions for best throughput
visibility_timeout	300	How long a message stays invisible while being processed (seconds)
visibility_extension_interval	60	How often to extend visibility for long-running tools (seconds)

Concurrency tip: max_messages and max_concurrent_executions together control parallelism:

polling:
  max_messages: 4                  # Fetch 4 messages at a time
execution:
  max_concurrent_executions: 4     # Process up to 4 in parallel

Recommended values for visibility:

• Fast tools (< 5 min): visibility_timeout: 300, extension_interval: 60
• Long tools (< 1 hour): visibility_timeout: 600, extension_interval: 120
• Very long tools: visibility_timeout: 900, extension_interval: 180

Execution

Controls tool execution behavior.

execution:
  default_timeout_seconds: 300
  max_timeout_seconds: 3600
  max_concurrent_executions: 4
  # work_directory: "/custom/path"  # Optional

Field	Default	Description
default_timeout_seconds	300	Tool timeout when the workflow doesn't specify one
max_timeout_seconds	3600	Hard cap on all executions. 0 = unlimited
max_concurrent_executions	4	Max parallel tool executions. Set based on CPU/memory
work_directory	OS temp + /beam-work	Where temporary files are stored during execution. Defaults to /tmp/beam-work on Linux

Timeout behavior:

Workflow requests 600s  → uses 600s (under max)
Workflow requests 7200s → capped at 3600s (max)
Workflow doesn't specify → uses 300s (default)

Logging

log_level: "info"
log_format: "json"

Field	Default	Options
log_level	info	debug, info, warning, error
log_format	json	json (structured, for production), text (readable, for development)

Agent Name

agent:
  name: "my-agent-01"

Optional — just affects log output. Default: beam-agent-01.

Configuration Profiles

High Performance

execution:
  max_concurrent_executions: 16
  max_timeout_seconds: 0
  work_directory: "/mnt/fast-ssd/beam-work"  # Optional: fast storage

polling:
  max_messages: 10

Long-Running Tools

execution:
  default_timeout_seconds: 3600
  max_timeout_seconds: 0

polling:
  visibility_timeout: 900
  visibility_extension_interval: 180

Development / Debugging

log_level: "debug"
log_format: "text"

execution:
  max_concurrent_executions: 1
  max_timeout_seconds: 0

Validation

The agent validates configuration on startup. Common errors:

# max_timeout must be >= default_timeout (or 0 for unlimited)
execution:
  default_timeout_seconds: 600
  max_timeout_seconds: 300  # Error!

Test your config manually:

python -c "
from beam_agent import BeamConfig
from pathlib import Path
config = BeamConfig.from_yaml(Path('config.yaml'))
config.validate_for_backend()
print('Configuration valid')
"

Troubleshooting

"Field required" error — A provisioned field is missing. Re-download your config from NINA.

"AWS configuration required" error — The aws: section is missing or incomplete.

Agent not processing messages? — Try increasing max_messages and max_concurrent_executions.

Tools timing out? — Increase default_timeout_seconds and max_timeout_seconds.

See Troubleshooting Guide for more.

Next Steps

• Create custom tools - Build your security tools
• Configure AWS IAM - Set up proper permissions