Simba — Etlworks AI Agent

Overview

Simba is the AI agent built into Etlworks. It is embedded in the application and can answer questions about the platform, build flows from natural-language descriptions in Composer, create connections (including HTTP API connections built from public vendor docs), browse data and run SQL through Explorer, write and review code in JavaScript and Python, manage schedules, and triage failing flows.

Simba is powered by frontier OpenAI models. The "intelligence" comes from the toolchain Simba operates through — the platform’s metadata, knowledge base, template library, CLI, and Composer canvas. Simba does not learn from your data: providers run Etlworks workloads under no-training agreements, and support-ticket content indexed for retrieval is anonymized before embedding.

Where Simba appears

Simba is available across the application surfaces where most work happens:

Top toolbar

Click the Simba icon to open or hide the chat panel.

Composer canvas

Click Build with Simba in Composer.

Simba can build, edit, and arrange flows directly on the Composer canvas as you describe what you want.

More on Composer →

Explorer

Click the Simba icon to open or hide the chat panel.

Simba can browse connections, list tables and columns, run SQL, and analyze sample results.

Code editors

Select AI Assistant tab in Code Editor.

Simba has context for JavaScript, Python, SQL, and CLI surfaces and can write, review, or fix code in-place.

Mapping editor

Simba is aware of source and destination field names and can suggest or auto-apply mappings.

What Simba can do

Answer questions and search the knowledge base

Ask Simba in plain language. Answers are grounded in the Etlworks knowledge base, the connector and template library, and prior support cases. Knowledge search runs against a vector index that prioritizes templates and current articles, so answers reflect how the platform actually works today rather than older documentation snapshots.

Knowledge search and Q&A are non-agentic: they do not consume from any usage allowance and have no per-tenant cap.

Build flows from natural language

Describe what you want — for example, "load Stripe charges into Snowflake every hour, full refresh for the first run and incremental after that" — and Simba builds the flow on the Composer canvas. Simba can:

• Add, update, delete, move, and group source/destination pairs.
• Set source, destination, and staging connections; choose or create the appropriate format; attach transformations and lookups.
• Configure loop conditions, error handling, and parallel execution.
• Add file-management blocks (copy, move, rename, delete, mkdir, split, merge, zip, unzip).
• Set or update the schedule.
• Save and run the resulting flow.

Composer covers any-to-any ETL, streaming (CDC and message queues), warehouse and bulk-load patterns (Snowflake, Redshift, BigQuery), and file-management flows. The canvas updates live while Simba works, so you see what is being built rather than only a final result.

Create connections, including HTTP API connections

Simba can create connections of any supported type by selecting the correct connector descriptor and filling in the required configuration. For HTTP/REST APIs, Simba can:

• Configure URL, method (GET/POST/PUT/PATCH/DELETE), content type, headers, payload, timeout, and success codes.
• Set up authentication: none, basic (preemptive or challenge), bearer, header, token, OAuth 2, OAuth 1, AWS signing, or JWT assertion.
• Use preconfigured HTTP-family descriptors for common SaaS APIs (Microsoft, HubSpot, Salesforce, Jira, Confluence, QuickBooks, Zoho, Google, Amazon Marketplace) or the generic HTTP descriptor for any other API.
• Read public API documentation directly from the web to determine the correct endpoint, parameters, and auth flow before creating the connection.

Operate the environment

Simba can inspect flows, connections, schedules, formats, and listeners; diagnose failed jobs by reading errors, schemas, and configs; monitor running flows; investigate disk usage and server health; and compare scheduled-versus-actual executions to flag drift.

Code, SQL, and CLI assistance

In code editors, Simba writes and reviews JavaScript transformations, Python scripts, SQL queries across the supported dialects, and CLI commands. It is aware of editor location and surrounding code context, so suggestions are scoped to what you are doing.

Templates and bootstrapping

Simba can search the full template library and import a template directly into your tenant. Templates cover hundreds of common integration patterns; using one as a starting point is typically faster than building from scratch.

Using Simba

Open the chat panel

Click the Simba icon in the top toolbar to open or hide the chat panel.

Four icons at the top of the chat panel control the conversation and its setup:

• New conversation — start a fresh chat. The previous conversation is preserved in history.
• Chat history — open the list of saved conversations to resume one.
• OpenAI API Key — set or remove a personal OpenAI API key (see OpenAI API key (BYOK)).
• Talk to a human — submit a support ticket without leaving Simba.

The chat input area also has voice controls — a microphone button to dictate prompts and a speaker button to have Simba read responses aloud.

Ask in plain language

Type what you want in natural language. For agentic tasks — anything that changes state, such as creating a connection, mutating a flow on the canvas, or running a CLI command — Simba describes the action first and waits for your approval before applying it.

Continue or resume conversations

Conversations are saved and can be resumed. Use the round close button to hide the chat window. Start a new conversation when you want a clean context; otherwise, Simba carries earlier turns forward so follow-ups stay coherent.

Configuring Simba

Super Admins configure Simba under Settings → AI.

Enable or disable AI features

AI is opt-in/opt-out at three scopes:

• Customer (on dedicated environments) — AI can be disabled for the entire customer.
• Tenant — AI can be disabled per tenant.
• User — individual users can disable AI for themselves.

The setting is all-or-nothing: it turns every AI feature on or off, including Q&A, knowledge search, Composer prompts, and the AI Agent API. There is no granular per-feature toggle. When AI is disabled at any scope, the Simba icon does not appear and AI tool calls are blocked for everyone in that scope.

OpenAI API key (BYOK)

An OpenAI API key can be set at three scopes: environment, tenant, or user. The most-specific scope wins — a user-level key takes precedence over a tenant-level key, which takes precedence over an environment-level key. When a key is configured, Simba uses it for inference and that OpenAI account is billed directly for inference costs.

If no key is configured at any scope, Simba uses the Etlworks-managed inference path and draws from your free agentic allowance (see Billing).

Billing and free allowance

Simba operations split into two billing modes:

• Non-agentic (free, no cap). Q&A, knowledge-base search, template search, and support-ticket creation do not consume from any allowance.
• Agentic (counted). Any tool call that changes state — creating a connection, running CLI, applying a Composer flow update, importing a template, web research, and similar — consumes from the agentic allowance.

Where the allowance is tracked depends on your environment:

• Shared environments (app.etlworks.com) — the free agentic allowance is tracked per tenant.
• Dedicated environments — the allowance is tracked per customer, pooled across all tenants the customer owns.

When the allowance is exhausted, you can top up a wallet for additional usage or bring your own OpenAI key (BYOK, see above) and pay your provider directly. Wallet activity and current balance are visible from the account-management menu.

More on billing →

Privacy and data handling

• No training on your data. Inference providers used by Etlworks (and by your BYOK account when you supply one) are contractually prohibited from training on enterprise traffic.
• Opt-in/opt-out at customer, tenant, and user scope. AI features can be turned off entirely at any of those three levels. The switch is all-or-nothing; there is no per-feature toggle.
• Approval required for agentic actions. Any tool call that changes platform state is described in the chat and waits for explicit user approval before executing.

Using Simba as a subagent (AI Agent API)

Simba is also available as a REST API. Give your applications and AI agents the power of Etlworks data integration: search knowledge bases, execute CLI commands, import templates, and have full conversations with Simba through a simple Bearer-token API. Use it as a subagent in LangChain, CrewAI, AutoGen, or any orchestration framework that delegates data-integration tasks to a specialist.

The AI Agent API supports:

• Direct tool access — call individual agent tools (knowledge-base search, CLI execution, template search and import, and more) without going through the LLM.
• Full agent chat — send messages and let the agent pick and chain tools to answer complex questions.
• Real-time streaming — stream responses token by token via Server-Sent Events, with in-progress tool calls and usage metrics in the stream.
• Multi-turn sessions — persistent sessions that carry context across messages for complex workflows.
• API-key auth — Bearer-token authentication, no OAuth flows.

Endpoints live under /rest/v1/ai-agent/api. Full developer documentation, quickstart, API reference, code examples, and Python / Bash / PowerShell clients are at:

https://etlworks.com/dev/ai/ — AI Agent API developer documentation

For the broader Etlworks REST API (flows, connections, schedules, executions, audit, and the rest of the platform), see https://etlworks.com/dev/api/.

Public Simba on etlworks.com

A public-facing Simba instance answers product questions on the Etlworks marketing site at etlworks.com. The public instance shares the same knowledge sources as the in-app assistant (docs, templates, marketing pages) but runs with a restricted system prompt and a whitelist of safe, non-agentic tools. It is intended for prospects and visitors evaluating the platform; in-tenant work happens in the application.

Permissions

Simba honors the role hierarchy of the user signed in to the application. Higher-privileged roles unlock more tool capabilities:

• Super Admin — configures AI settings; full tool access.
• Administrator — full operational tool access within the tenant.
• Editor — create and modify flows, connections, formats.
• Operator — run, monitor, and diagnose flows; no metadata mutations.
• Viewer — Q&A, knowledge search, read-only inspection.
• API User — programmatic access through the AI Agent API; scope mirrors the user’s assigned role.

Enabling Simba in airtight on-premise environments

Simba is the on-by-default AI agent built into Etlworks. On cloud and most on-premise deployments there is nothing to configure — Simba is reachable from the chat panel in the UI and the /rest/v1/ai-agent/api and /rest/v1/ai-agent/mcp endpoints as soon as you log in. On strictly airtight or proxied networks, however, Simba needs outbound access to a small list of services to function. This section lists those services and explains the three places Simba can be turned on or off.

Outbound network requirements

All connections are outbound HTTPS over TCP port 443. No inbound connections from any of these services to the Etlworks instance are required. Standard outbound DNS (UDP / TCP port 53 to your resolvers) is needed to resolve the hostnames.

Required — Simba will not work without these.

Required if you use the built-in Billing UI.

Optional — depends on which Simba features and integrations you turn on.

All of the hostnames above sit behind CDNs (Cloudflare, Fastly, AWS) with rotating IP ranges, so no static IP allowlist is published. If your firewall policy requires hostname-level filtering, configure it on your egress proxy (Squid, Zscaler, Palo Alto URL filtering, etc.) rather than at the IP layer. If you must pin by IP, OpenAI's API is fronted by Cloudflare and is covered by Cloudflare's published IP ranges (cloudflare.com/ips/), but that allowlist is wide — every Cloudflare-fronted service is included.

If you bring your own OpenAI API key (BYOK), the LLM calls still go to api.openai.com — same host, just authenticated with your key — so the firewall rules do not change. If you point Simba at an OpenAI-compatible endpoint other than OpenAI itself (a private LLM gateway, an Azure OpenAI deployment, etc.), the corresponding hostname replaces api.openai.com in the required list.

Enabling and disabling Simba (instance, tenant, user)

Simba can be turned off from three different places. The instance-level switch overrides everything below it; the tenant-level switch overrides per-user choices; and the per-user controls let an individual user opt into using their own OpenAI key instead of the shared one. A change at any level takes effect on the next request — no restart required.

Instance level (whole on-premise deployment). A super admin disables Simba for the entire deployment by setting etlworks.ai.agent=false in application.properties and restarting the integrator, or by pushing ai.agent.enabled=false from the license server (no restart). When the instance-level switch is off, the Simba chat panel, the /rest/v1/ai-agent/api REST endpoints, and the /rest/v1/ai-agent/mcp MCP endpoint all return "AI features are disabled for this account" or 403 to any caller, regardless of tenant or user.

This is the right control to use when an on-premise customer wants to fully turn Simba off — for example, while completing a security review before allowing outbound traffic to api.openai.com.

Tenant level. A super admin disables Simba for a specific tenant in two equivalent ways. Both are checked on every request; either being on disables AI for the tenant.

1. From the tenant configuration UI, toggle Disable AI on the tenant record. (This sets the disable_ai flag on the tenant.)
2. From the tenant's AI Settings, set the Disable AI features setting to true. (This sets the disable.ai.features per-tenant setting.)

When AI is disabled for a tenant, users in that tenant see Simba's chat panel as unavailable, and any tool call, REST API call, or MCP call from that tenant returns 403 with "AI features are disabled for this account". Other tenants on the same instance are unaffected.

User level (BYOK opt-in). Etlworks does not currently expose a per-user "disable AI" toggle. What an individual user can control is who pays for the OpenAI tokens they consume. From My Profile → API Keys, a user can configure their own OpenAI API key and choose to use it for their own Simba sessions. When this preference is enabled, the user's chat turns are billed to their OpenAI account and do not count against the tenant's Etlworks AI cap or wallet. When it's disabled, the tenant's or instance's configured OpenAI key is used.

If you need to prevent a specific user from using Simba at all, the supported approach today is to disable AI at the tenant level (which affects every user in that tenant) or to remove the user's permission to access the chat panel via standard role-based access control. A fine-grained per-user AI on / off switch is on the roadmap but not in the current release.

Recap

Configuring the OpenAI endpoint and models (application.properties)

On dedicated and on-premise deployments you can point Simba at any OpenAI-compatible API — the hosted OpenAI API, a private gateway or proxy, or a self-hosted deployment — and override which models it uses. All of these settings live in application.properties on the Etlworks instance and take effect on restart. 

IMPORTANT: Using a custom endpoint or custom models requires you to configure your own OpenAI (or compatible) API key via openai.api.key. This scenario cannot rely on license-server configuration.

Step 1 — Set the API key.

openai.api.key=sk-...your key...

Required. This is the key Simba authenticates with (sent as an Authorization: Bearer <key> header). For a custom gateway, use whatever bearer token that gateway expects.

Step 2 — (Optional) Point at a custom API base URL.

# Base URL of your OpenAI-compatible API, up to and including the version segment.
# Default: https://api.openai.com/v1
ai.openai.api.url=https://your-gateway.example.com/v1

Both the chat-completions endpoint and the embeddings endpoint are derived from this one base URL (<base>/chat/completions and <base>/embeddings), so a single value redirects all of Simba's OpenAI traffic. Leave it unset to use the hosted OpenAI API.

The value is tolerant of common formats — a bare host (api.openai.com), a value with or without a trailing slash, or even a full endpoint URL — but the recommended form is the base including the version segment, for example https://api.openai.com/v1.

Step 3 — (Optional) Override the models.

# Main in-app assistant + REST scripting API + MCP. Default: gpt-5.1
ai.agent.model=gpt-5.4

# Lightweight routing/classification model. Default: gpt-5.4-mini
ai.agent.routing.model=gpt-5.4-mini

# Embedding model used for the knowledge base. Default: text-embedding-3-small
ai.openai.embeddings.model=text-embedding-3-small

Set these to whatever model identifiers your endpoint exposes. If you are using the hosted OpenAI API you can leave them at the defaults.

Step 4 — Restart the Etlworks instance.

application.properties is read at startup, so restart the instance for the changes to take effect.

Properties reference

Notes

• Bearer auth only. Simba sends the key as Authorization: Bearer <key>. A custom endpoint works as long as it accepts a Bearer token and speaks the OpenAI Chat Completions and Embeddings request/response shapes (including streaming). Endpoints that require a different auth scheme — for example a raw Azure OpenAI api-key header, or AWS Bedrock request signing — are not supported by a URL swap alone.
• Embedding dimensions. The knowledge-base vector store expects 1536-dimension embeddings (the default text-embedding-3-small size). If you change ai.openai.embeddings.model to a model with a different native dimension, you must re-run the knowledge-base sync so the vectors match, or search will not work. Changing the chat models has no such constraint.
• One base URL for everything. You do not set the chat and embeddings URLs separately — both are derived from ai.openai.api.url. If your gateway hosts chat and embeddings at non-standard sub-paths, that is not currently configurable; the derived paths are always <base>/chat/completions and <base>/embeddings.
• Per-user “bring your own key.” Individual users can still configure their own OpenAI key in My Profile → API Keys; that key is used for their sessions but routes to the same ai.openai.api.url endpoint. The instance-wide openai.api.key is the fallback for everyone else.
• Advanced. An optional ai.openai.embeddings.dimensions property can pin a larger embedding model to the knowledge base's 1536 size. Leave it unset unless you specifically need it.

Example — private gateway

# Point Simba at a private OpenAI-compatible gateway
openai.api.key=<gateway-bearer-token>
ai.openai.api.url=https://ai-gateway.internal.acme.com/v1
ai.agent.model=gpt-5.4
ai.agent.routing.model=gpt-5.4-mini
ai.openai.embeddings.model=text-embedding-3-small

Restart the instance after saving.

FAQs

Which model does Simba use?

Simba runs on the latest frontier OpenAI model. As of this release, that is GPT-5.4. The model is selected by Etlworks (or by you, via BYOK) rather than the user, so Simba stays on the current generation as new frontier models ship — the platform tracks them automatically.

Can I turn Simba off entirely?

Yes. A Super Admin can disable AI features for the tenant under Settings → AI. With AI disabled, the toolbar icon does not appear and the AI Agent API rejects requests.

Does my data leave Etlworks when I use Simba?

Only the parts of the conversation that need a model response are sent to the inference provider, and only under no-training agreements. For BYOK, your data goes to your OpenAI account on your contractual terms. For air-gapped deployments, no data leaves your network because the model itself runs on your infrastructure.

Why is Simba’s answer different from an older article I remember?

Simba’s knowledge index is refreshed continuously. When documentation is rewritten, Simba prefers the current version and may answer differently than older content you have seen before. If you suspect Simba is wrong, check the linked source it cites.