Working with agents¶

Agent nodes enable a different way of building workflows in OPAQUE. Instead of defining a fixed sequence of steps, you define a goal and give an agent access to the capabilities it can use to reach that goal at runtime.

This guide assumes you’ve completed the Get started guide and are familiar with creating and launching workflows. It focuses specifically on:

• The core building blocks of non-deterministic, or agentic, workflows (Agent, model, and tool-enabled nodes)
• How to design an agentic workflow so the agent can choose appropriate actions at runtime
• How to configure agent goals and tool descriptions so they work well together

Agent reasoning model¶

An Agent node doesn’t execute as a single, one-off step. Instead, it runs a controlled reasoning loop: it evaluates the goal and current input, decides whether it needs more information, and may invoke one or more tools before producing a final response.

At a high level, the loop works like this:

1. The agent receives its goal, the incoming prompt, and a list of available tools.
2. It evaluates whether it already has enough information to produce a response.
3. If not, it selects an appropriate tool and supplies structured inputs.
4. The tool returns structured output.
5. The agent reassesses its goal in light of the new information.
6. This process continues until the agent determines it can produce a final result.

This is why agentic workflows are designed around capabilities (tools + descriptions), not a hard-coded sequence of steps. The agent isn’t autonomous in an open-ended sense; it can only act within:

• The tools you explicitly connect
• The descriptions you provide for those tools
• The constraints of the workflow itself

Understanding this execution model explains why agentic workflows behave differently from deterministic ones, and why tool descriptions and observability matter when debugging agent behavior.

Core building blocks of an agentic workflow¶

Every agentic workflow uses the same building blocks: an Agent node, a model that powers it, and one or more tools the agent can invoke.

The Agent node¶

The Agent node is the decision-making core of the workflow. It reasons about a goal, evaluates context, and decides what to do next.

Unlike standard nodes, which perform a single predefined operation, the Agent node may:

• Call one or more tools
• Skip tool calls and respond directly
• Combine multiple tool results into a single response

The Agent node itself does not store data or retrieve information. It coordinates other nodes to achieve its goal.

A language model (LLM)¶

The agent’s reasoning is powered by a language model connected to the Agent node. The model determines how the agent interprets the goal, understands tool descriptions, and produces responses.

The model doesn’t define workflow behavior on its own—the agent goal and tool descriptions do that—but model choice can affect how reliably the agent follows instructions and uses available tools.

Tools¶

Tools are how agents access data and take actions beyond pure reasoning.

In OPAQUE, tools are represented by tool-enabled nodes that are made available to the agent at runtime, such as:

• Data connectors (for example, Azure AI Search or PostgreSQL)
• MCP-based API tools

These nodes are not part of the main Start → End execution path. Instead, they’re registered with the workflow and exposed to the agent, which decides whether, when, and how to invoke them. Some tools are built-in connectors; others are defined via MCP when you need to call external APIs.

Designing an agentic workflow¶

Building an effective agentic workflow starts with clear separation of responsibilities: the agent decides what to do, and tools provide the data and actions it needs.

Step 1. Place and connect the nodes you need¶

At a minimum, an agentic workflow includes:

• An Agent node
• A tool-enabled model connected to the Agent’s Model handle
• One or more tool-enabled data connectors or utilities connected to the Agent’s Tools handle

You still connect Start → Agent → End to define the entry and exit points of the workflow. The difference is that most data access and actions happen through the Agent’s tool calls.

The following example shows a simple agentic workflow that answers questions about leave balances, claims, and employee directory information. It consists of:

• An Agent node (hr_assistant_agent)
• A model (OpenAI Service Integration)
• Three tools:
  • Two PostgreSQL connectors (claims_tool, leave_balance_tool)
  • An employee directory tool (employee_info_tool) defined via MCP

This structure gives the agent everything it needs to retrieve the right data and respond without hard-coding a fixed sequence of checks.

Step 2. Define a clear agent goal¶

The Agent goal is the most important part of configuration. It frames how the agent reasons and remains stable across executions.

A good agent goal:

• Describes what the agent is responsible for, and optionally includes reusable procedures and output formats for common tasks (avoid one-off, request-specific instructions)
• Is durable and high-level
• Avoids embedding request-specific input

It’s often helpful to include standard procedures for repeatable tasks (for example, what a “departmental leave report” means and the format it should follow). Keep these procedures generic and reusable, and rely on tools for the live data.

Think of the goal as the agent’s role description plus any reusable playbooks you want it to follow consistently.

For example, the goal for the HR assistant agent in the previous example might look like this:

You are an HR assistant. Help employees with questions about leave balances, expense claims, and employee directory information.

For each request:
1. Identify which tool(s) can provide the needed data.
2. Use tools to fetch current information.
3. Respond using only the returned results.

Rules:
- If a request requires an employee record and employee_info_tool returns no match, stop and report that the employee was not found.
- If the request does not include an employee identifier (email or name) and one is required, ask for the missing information instead of guessing.

Standard outputs:
- “Departmental leave report” = a summary by department with:
  - department name
  - employee count included
  - vacation_leave_balance_approved totals (and/or averages, if requested)
  - sick_leave_balance_approved totals (and/or averages, if requested)
  - time window (ask if not provided; otherwise state what you assumed)
- When asked to “generate a report” and then analyze it, produce the report first, then clearly separate an “Analysis” section that references the report numbers.

Tools available:
- employee_info_tool (employee directory)
- leave_balance_tool (leave balances)
- claims_tool (expense claims)

Step 3. Provide strong tool descriptions¶

Treat tool descriptions as part of the agent’s instructions. Agents decide which tools to call—and how to call them—based on what you write here. If the schema, constraints, or query rules aren’t explicit, the agent will guess.

A strong tool description:

• Explains what the tool does and when to use it
• Specifies what data it can access (tables/collections, key fields)
• Describes what the output contains and how to interpret it
• Documents how to call it (required inputs, expected formats)
• Notes important constraints or assumptions (limits, filters, query rules)

For example, a PostgreSQL tool querying time-off data might be described as:

Query employee leave balances from the PostgreSQL database.

Table: timeoff

Columns (exact names):
- email (text) — employee email
- emp_name_en (text) — employee name
- vacation_leave_balance_approved (text) — vacation days
- sick_leave_balance_approved (text) — sick days

Query rules:
- Use literal values in WHERE clauses (example: WHERE email = 'john.doe@scb.co.th').
- Do not use parameter placeholders (for example, :email).

A claims database tool description might include:

Query employee expense claims from the PostgreSQL database.

Table: claims

Columns (exact names):
- email_submitter (text) — employee email
- submitter_name (text) — employee name
- claim_type (text)
- claim_amount (text)
- status (text)

Query rules:
- Use literal values in WHERE clauses.
- Do not use parameter placeholders.

Tool descriptions are one of the most common failure points in agentic workflows. Investing time here usually pays off more than tweaking prompts or model settings.

Step 4. Test your workflow¶

Once the workflow is designed, use Test mode to validate agent behavior end-to-end and see what the agent is doing at each decision point. In particular, confirm:

• Which tools it calls (and in what order)
• What inputs it sends to each tool
• How it uses returned data to produce its final response
• Whether tool descriptions are working as intended (for example, the agent consistently picks the right tool and queries it correctly)

TTest mode is especially useful for agentic workflows because execution paths can vary run to run. For step-by-step instructions, see Using test mode.