Downloads

Client scripts and libraries for integrating with the Etlworks AI Agent API. All scripts are self-contained, no build step required.

Python client library

etlworks_agent.py

Full-featured Python client. Use as an importable library in your code or as a standalone CLI tool. Supports all endpoints: tools, chat, streaming, and sessions.

Download .py

Requirements

Shell

pip install requests

Quick start

Python

from etlworks_agent import EtlworksAgent

agent = EtlworksAgent(
    base_url="https://your-instance.etlworks.com",
    api_key="your-api-key"
)

# List tools
tools = agent.list_tools()
print(tools)

# Chat
result = agent.chat("How do I create a REST connection?")
print(result["response"])

# Stream
for event in agent.chat_stream("What are the main features?"):
    if event["type"] == "token":
        print(event["content"], end="", flush=True)

# Session (multi-turn)
session = agent.create_session()
r1 = agent.session_chat(session, "How do I create a connection?")
r2 = agent.session_chat(session, "Now schedule it daily")

# Direct tool call
kb = agent.execute_tool("search_knowledge_base", {"query": "REST connection"})
print(kb["result"])

Shell

export ETLWORKS_URL="https://your-instance.etlworks.com"
export ETLWORKS_API_KEY="your-api-key"

python etlworks_agent.py tools
python etlworks_agent.py tool search_knowledge_base '{"query": "REST"}'
python etlworks_agent.py chat "How do I create a connection?"
python etlworks_agent.py chat-stream "How do I schedule a flow?"
python etlworks_agent.py session-create
python etlworks_agent.py session-chat SESSION_ID "Follow-up question"
python etlworks_agent.py session-messages SESSION_ID

API methods

Method	Description
`list_tools()`	List all tools with schemas
`execute_tool(name, args)`	Execute a tool directly
`chat(message, ...)`	One-shot chat (complete response)
`chat_stream(message, ...)`	One-shot chat (streaming generator)
`create_session()`	Create a multi-turn session
`session_chat(id, message)`	Chat in session (complete)
`session_chat_stream(id, msg)`	Chat in session (streaming)
`session_messages(id)`	Get session history

Bash client script

etlworks-agent.sh

Standalone Bash script using curl and jq. No dependencies beyond standard Unix tools. Supports all endpoints including real-time SSE streaming.

Download .sh

Requirements

curl (pre-installed on macOS/Linux)
jq (recommended for pretty output; optional)

Quick start

Shell

chmod +x etlworks-agent.sh
export ETLWORKS_URL="https://your-instance.etlworks.com"
export ETLWORKS_API_KEY="your-api-key"

./etlworks-agent.sh help
./etlworks-agent.sh tools
./etlworks-agent.sh tool search_knowledge_base '{"query": "REST connection"}'
./etlworks-agent.sh chat "How do I create a connection?"
./etlworks-agent.sh chat-stream "How do I schedule a flow?"

SESSION=$(./etlworks-agent.sh session-create)
./etlworks-agent.sh session-chat $SESSION "How do I create a connection?"
./etlworks-agent.sh session-chat $SESSION "Now schedule it to run hourly"
./etlworks-agent.sh session-messages $SESSION

Commands

Command	Description
`tools`	List available tools
`tool <name> <args>`	Execute a tool
`chat <message>`	One-shot chat
`chat-stream <message>`	Streaming chat
`session-create`	Create session (prints ID)
`session-chat <id> <msg>`	Chat in session
`session-chat-stream <id> <msg>`	Stream in session
`session-messages <id>`	Get session history

PowerShell client script

etlworks-agent.ps1

Native PowerShell script for Windows. Uses built-in Invoke-RestMethod, no external modules required. Supports all endpoints including real-time SSE streaming. Works on PowerShell 5.1+ (Windows) and PowerShell Core 7+ (cross-platform).

Download .ps1

Requirements

PowerShell 5.1+ (pre-installed on Windows 10/11) or PowerShell Core 7+ (cross-platform)
No external modules: uses built-in Invoke-RestMethod and System.Net.HttpWebRequest

Execution policy

If you get a script execution error, you may need to allow script execution for the current session:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Quick start

PowerShell

$env:ETLWORKS_URL = "https://your-instance.etlworks.com"
$env:ETLWORKS_API_KEY = "your-api-key"

.\etlworks-agent.ps1 help
.\etlworks-agent.ps1 tools
.\etlworks-agent.ps1 tool search_knowledge_base '{"query": "REST connection"}'
.\etlworks-agent.ps1 chat "How do I create a connection?"
.\etlworks-agent.ps1 chat-stream "How do I schedule a flow?"

$session = .\etlworks-agent.ps1 session-create
.\etlworks-agent.ps1 session-chat $session "How do I create a connection?"
.\etlworks-agent.ps1 session-chat $session "Now schedule it to run hourly"
.\etlworks-agent.ps1 session-messages $session

Commands

Command	Description
`tools`	List available tools
`tool <name> <args>`	Execute a tool
`chat <message>`	One-shot chat
`chat-stream <message>`	Streaming chat
`session-create`	Create session (outputs ID)
`session-chat <id> <msg>`	Chat in session
`session-chat-stream <id> <msg>`	Stream in session
`session-messages <id>`	Get session history

OpenAPI spec

etlworks-ai-agent-api.openapi.yaml

OpenAPI 3.1 description of the eight AI Agent API endpoints: tools, chat, streaming chat and sessions. Also available as JSON. The platform REST API has its own spec.

Download YAML

MCP, no download required

Etlworks MCP server

Already using Cursor, Claude Desktop, or ChatGPT? Etlworks ships an MCP server you can connect directly, no Etlworks client library needed. Same tools as the REST API, same API key, native to your AI client.

MCP setup guide

Subagent integration examples

subagent_example.py

Complete examples showing how to use Etlworks as a subagent within an orchestration framework. Includes patterns for direct tool calling, delegation, sessions, streaming, and routing.

Download .py

Included examples

Example	Description
`tools`	Direct tool calling: fast, deterministic, no LLM
`chat`	One-shot delegation to the agent
`session`	Multi-turn session for complex workflows
`stream`	Streaming for real-time UI display
`orchestrator`	Routing pattern for multi-subagent orchestrators

Shell

# Run a specific example
python subagent_example.py tools
python subagent_example.py chat
python subagent_example.py session
python subagent_example.py stream
python subagent_example.py orchestrator

# Run all examples
python subagent_example.py all

Configuration

All client scripts are configured via environment variables:

Variable	Required	Default	Description
`ETLWORKS_URL`	No	`http://localhost:8080`	Your Etlworks instance URL
`ETLWORKS_API_KEY`	Yes	:	API key for authentication

Generating an API key

Most users generate their own key under Preferences → Security → API key. Admins and super admins can create one for any user under Settings → Users → select the user → Security → API key. Make sure Allow API key authentication is enabled: the key authenticates calls instead of a JWT token.

Security best practices

Store API keys in environment variables or a secrets manager
Never commit API keys to source control
Use separate API keys for development and production
Set expiration dates on API keys when possible
Use a dedicated "API User" account with minimal required permissions