Agents Overview
An agent in TARX is a reusable LLM configuration. Think of it as a job description for an AI worker: you define the model, the persona (system prompt), the tools it can use, the knowledge it can access, and the external servers it can connect to. Once configured, an agent can be placed into any number of workflows and used repeatedly.
Agents are not tied to a single workflow. Create an agent once — a "code reviewer", a "content writer", a "security analyst" — and reuse it across all your workflows.
The Agent Model
Each agent is stored with the following conceptual structure:
Identity Fields
| Field | Type | Description |
|---|---|---|
name | string | Short identifier, becomes the expression variable: {{name.output}} |
icon | emoji | Visual icon on the canvas node and in lists |
description | string | Human-readable description of what this agent does |
LLM Config Fields
| Field | Type | Description |
|---|---|---|
user_api_key_id | string | Reference to the project's encrypted LLM key |
model | string | Model identifier (e.g., gpt-4o, claude-sonnet-4-6) — picked from the live list for your key |
temperature | float (0.0–2.0) | Controls randomness. 0.0 = deterministic, 1.0+ = creative |
max_tokens | int | Maximum tokens in the response |
Prompt Fields
| Field | Type | Description |
|---|---|---|
system_prompt | string | The agent's core instructions and persona |
Enrichment Fields
| Field | Type | Description |
|---|---|---|
capabilities | dict | Which built-in tools are enabled (web_search, web_scraper) |
skill_id | string | Optional: a skill whose system_prompt is merged in |
rag_sources | list | IDs of RAG sources to query before each LLM call |
mcp_servers | list | IDs of MCP server configs; tools discovered at runtime |
Agent Enrichment Layers
Agents can be enriched with four layers of additional capabilities:
1. Capabilities
Built-in tools that TARX executes server-side. Enable them via toggles in the Agent Editor. When enabled, the corresponding tool definition is injected into the LLM's tool list.
Available capabilities (2):
web_search— Search the web and return resultsweb_scraper— Extract text content from URLs
The capability set is deliberately minimal. To call an API inside a workflow, use the dedicated http_request node (a workflow node, not an agent capability). For database/SaaS integrations, attach an MCP server. See Capabilities for full details.
2. Skills
A skill is a reusable prompt preset. When you assign a skill to an agent, the skill's system_prompt is merged into the agent's own system prompt at runtime. Skills are LLM-agnostic — any agent on any provider/model can use any skill.
Skills let you quickly apply battle-tested instructions without writing prompts from scratch. TARX provides built-in skills (e.g., "Senior Code Reviewer", "SEO Content Writer") and you can create custom ones.
See Skills for details.
3. RAG Sources
When an agent has RAG sources configured, TARX queries those vector databases before every LLM call. The top-k matching chunks from each source are injected into the LLM's context as system-level retrieved context.
This lets your agents have access to domain knowledge, documentation, or project-specific data without it needing to be in the system prompt.
See RAG Enrichment for details.
4. MCP Servers
MCP (Model Context Protocol) servers are external tool servers. When assigned to an agent, TARX connects to the server at runtime, performs the handshake, and discovers available tools. Those tools are added to the LLM's tool list alongside capability tools.
MCP lets your agents access enterprise systems, specialized APIs, or custom internal tools — all as native agent tools.
See MCP Integration for details.
Relationship to Workflows
Agents are configured independently from workflows. On the canvas, an Agent Node references an agent by ID. Multiple workflow nodes can reference the same agent:
If you update an agent's system prompt, all workflows using that agent automatically get the updated behavior on the next run. This is powerful but requires care — always test agents after changes before running production workflows.
BYOK and Agent Execution
Each agent references a user_api_key_id — the ID of the project LLM key to use for that agent's calls. When a workflow node runs:
- The executor reads the agent's key reference
- Fetches the encrypted key from the agent's project (project-scoped, shared across members)
- Decrypts it in-memory using TARX's encryption infrastructure
- Passes the raw key to LiteLLM as
api_key=— it never touches disk or logs
Because keys are project-scoped, any member can run the agent; provider usage bills to the project key's underlying provider account, regardless of who triggers the workflow.
Agent Scoping
Agents are project-scoped. An agent belongs to exactly one project and can only be used in workflows within that project. To use the same agent in a different project, you'd need to create a copy.
Exception: Builtin agents (is_builtin=true) are readable by all authenticated users but can only be created by platform administrators. These are reference implementations and templates.
What's Next
- Creating Agents — Full walkthrough of the Agent Editor
- Models and Providers — What models you can use and how to specify them
- System Prompts — Writing effective prompts for your agents
- Capabilities — Web search and web scraping
- Testing Agents — Using the built-in test console