Use task agent best practices

Choose between task agent steps and deterministic steps

Not every workflow task requires an LLM. Use task agent steps only when the task involves interpretation, reasoning, or unstructured data. For predictable, rule-based operations, use deterministic step types instead.

You can also combine both types in a single workflow. Place the task agent step where interpretation is needed. Pass its structured output to downstream deterministic steps through the expression and variable system. For example, a task agent step can analyze an incident alert and classify its severity. A conditional step can then route the workflow based on that classification.

Use a task agent step when:

• The task requires interpreting unstructured text, such as error logs, support tickets, or monitoring alerts.
• The decision depends on context that you cannot express as a fixed set of rules.
• The task involves generating, summarizing, or transforming natural language content.
• You need to classify or categorize inputs where the categories or criteria might evolve over time.

Use a deterministic step instead when:

• The logic follows a fixed set of rules or conditions. Use a conditional step to evaluate expressions and route the workflow along true or false branches.
• The task calls an external API with known parameters. Use a REST API step for direct API calls.
• The task runs a script, shell command, or Ansible playbook with defined inputs and outputs. Use a script step or Ansible Automation Platform job template step.
• The task iterates over a list of items and performs the same operation on each one. Use a loop step.

Prompt and response schema interaction

The prompt and response schema work together to shape the agent's output. When a task agent step returns a free-text response, downstream steps must parse the text to extract specific values.

An LLM can be inconsistent by varying its wording, formatting, or structure across runs. A response schema solves this problem by instructing the agent to return a structured JSON object that conforms to a schema you define. Downstream steps can then reference individual fields with expressions, eliminating the need for text parsing.

When you provide a JSON response schema, the platform uses a cascading fallback strategy to ensure the agent's response matches your schema. This fallback mechanism is automatic and transparent. The output data can give you data about the strategies used.

Write effective prompts

Follow these guidelines when you write prompts:

• State the task in a single, direct instruction. Start with an action verb, such as "Analyze," "Classify," "Summarize," or "Extract."
• Define the expected output format in the prompt. Describe the fields, structure, and value types that the agent must return. For example: Analyze the logs and return a JSON object with an analysis_summary, severity, and recommended_action.
• When you need a strict format, define a response schema in the step configuration to enforce JSON schema validation on the output.
• Provide context boundaries. Tell the agent what information is relevant and what to ignore. Use phrases such as "Based only on the following input" to prevent the agent from introducing information that is not in the workflow data.
• Include examples when the task involves classification or categorization. Show one or two input-output pairs so the agent can infer the pattern.
• Use template expressions to inject runtime data into the prompt. The system resolves all expressions before sending the prompt to the LLM, so the agent receives concrete values, not raw syntax. For example, use expressions to pass error messages, ticket descriptions, or outputs from earlier steps directly into the prompt text.
• Upload context files when the agent needs reference data, such as policy documents, runbook excerpts, or classification guidelines. The agent reads these files before processing the prompt. You can upload up to 10 files in PDF, DOC, DOCX, TXT, or MD format.

Write effective response schemas

Make sure your response schema uses structured JSON. Follow these guidelines:

• Use description fields in your schema properties. The LLM uses these descriptions to understand what each field should contain, which improves the accuracy of structured output.
• Use required to mark only the fields you truly need. Making every field required increases the chance of validation failures, especially for complex schemas.
• Use enum for fields with a fixed set of values. This constrains the agent's output to known values, which is particularly useful for classification and routing tasks.
• Keep schemas focused. Define only the fields that downstream steps consume. Large, deeply nested schemas are harder for the LLM to satisfy consistently.
• Make sure the schemas do not conflict with the agent's prompts.

Manage context files

Manage context files that you upload to task agent steps to optimize storage and keep workflows clean:

Control LLM costs

Each task agent step sends a request to an LLM provider, which charges based on the number of tokens processed. To manage costs effectively, limit what you send and constrain what you receive.

Reduce input tokens

• Pass only the data the agent needs. Use template expressions to extract specific fields from earlier step outputs rather than forwarding entire payloads.
• Upload only the sections of reference documents that are relevant to the task. Shorter, targeted context files reduce token consumption and improve response quality. Note: When context files exceed the token budget, the system automatically compresses them by summarizing content while preserving document citations for traceability. However, compression itself consumes tokens, so starting with concise files is more cost-effective.

Reduce output tokens

• Define a response schema to constrain the agent's output to the specific fields your workflow needs. Without a schema, the agent might return verbose explanations or unnecessary detail.
• Write prompts that request concise responses. For example, instruct the agent to "Return only the severity level and a one-sentence justification" rather than asking for a full analysis.

Limit tool usage

• Restrict which tools the agent can access by setting the tool access strategy. Each tool call adds tokens to the conversation and incurs additional processing time.
• Select No tools when the agent only needs to analyze input data and return a response.
• Select specific tools when the agent needs to interact with external systems, rather than making all tools available.

Monitor usage

• Review execution results to see which tools the agent called and how many iterations it performed. If an agent consistently calls tools that do not contribute to the final result, remove those tools from its configuration.
• Track token counts and response times in your run history to identify steps that consume more resources than expected.

Use conditional steps for range checking

After a task agent step, add a conditional step to verify that the output values fall within acceptable ranges. For example, if the agent returns a severity score, check that the value is between 1 and 5 before routing the workflow.

Handle failures explicitly

Task agent steps can produce unexpected or incorrect output. A task agent step that fails schema validation or encounters an LLM error moves to the Failed state.

Design your workflow to handle this case. You can use condition branches or subsequent steps to detect failures and take corrective action, such as retrying with a simplified prompt or routing to a manual review queue.

Test iteratively

• Run the workflow with representative sample data before publishing to production. Review the agent's output in the step Output pane to verify that it meets your expectations.
• Vary the input data to test edge cases, such as empty fields, unusually long text, or ambiguous inputs that could lead to unexpected classifications.