Docs / Guides / Prompt Engineering

Prompt Engineering

How to write task prompts that produce reliable, structured results from Ploton — patterns for AI agents, not humans.

Why this matters

The prompt field in a Ploton task is how your agent tells Ploton what to do. A precise prompt gets you structured, correct results fast. A vague one gets you data you can’t use.

This guide covers prompt patterns for AI agents that generate Ploton task prompts programmatically. The goal is machine-readable precision, not prose.

Core principles

1. Specify the outcome, not just the action

Tell Ploton what you need back, not just what to do. “Connect to the CRM” is an action. “Pull all contacts created in the last 30 days and return their name, email, and company” is an outcome with a defined shape.

Weak:

Connect to the CRM

Strong:

Connect to the user's CRM account and retrieve all contacts
created in the last 30 days. Return name, email, and company name
for each contact.

The weak prompt succeeds (Ploton connects) but your agent gets nothing useful back. The strong one returns data your agent can act on.

2. Name the service explicitly

Ploton supports many services. Don’t make it guess.

Weak:

Get me some customer data

Strong:

Query the connected payment service for all customers with active
subscriptions. Return customer_id, email, plan_name, and monthly_amount.

3. Include user context

If a task involves a specific user’s account, pass their user_id in the task creation call and reference the relevant details in the prompt.

Weak:

Send an email about the invoice

Strong:

Send an email to user_123's primary email address with their
latest invoice (invoice_456) attached as a PDF. Subject line:
"Your January 2025 Invoice". Use the monthly_invoice template
in the connected email service.

4. Specify the response format

If your agent expects data in a particular shape, say so. Ploton returns structured JSON, but the shape depends on what you ask for.

Weak:

Get the user's calendar events

Strong:

Get all calendar events for user_123 from their connected calendar
for the next 7 days. Return as a JSON array with fields: title
(string), start_time (ISO 8601), end_time (ISO 8601), attendees
(array of email strings).

5. Define failure behavior

For tasks that can’t silently fail, tell Ploton what to do when things go wrong. There are built-in recovery strategies, but you can steer them with the prompt.

Connect to the user's CRM account and pull their pipeline
deals. If the OAuth token is expired, trigger a re-authorization
flow. If the service is unavailable, retry up to 3 times with
exponential backoff.

Prompt templates

Your agent fills these in programmatically. Copy the pattern, swap the placeholders.

Data retrieval

Retrieve [WHAT] from [SERVICE] for user [USER_ID].
Filter by [CONDITIONS].
Return as JSON with fields: [FIELD_LIST].

Example:

Retrieve all deals from the connected CRM for user user_123.
Filter by stage = "Negotiation" and close date within 30 days.
Return as JSON with fields: deal_name, amount, close_date,
contact_email.

Action execution

Using [SERVICE], [ACTION] with the following parameters:
- [PARAM_1]: [VALUE_1]
- [PARAM_2]: [VALUE_2]
Confirm the action was completed and return [RESULT_FIELD].

Example:

Using the connected email service, send an email with the
following parameters:
- to: [email protected]
- template: welcome_v2
- subject: "Welcome to Acme"
- variables: { "name": "Jane", "plan": "Pro" }
Confirm delivery and return the message_id.

Multi-step workflow

Complete the following steps for user [USER_ID]:
1. [STEP_1]
2. [STEP_2] using the result from step 1
3. [STEP_3]
Return the final result from step 3.

Example:

Complete the following steps for user user_456:
1. Fetch their latest invoice from the payment service
2. Generate a PDF summary with invoice amount, date, and line items
3. Upload the PDF to their connected cloud storage "Invoices" folder
Return the file URL.

Conditional execution

Check [CONDITION] for user [USER_ID] via [SERVICE].
If true: [ACTION_A].
If false: [ACTION_B].
Return which path was taken and the result.

Example:

Check if user user_789 has an active subscription in the
payment service.
If true: retrieve subscription details (plan, amount, next billing date).
If false: return { "has_subscription": false }.
Return which path was taken and the result.

Anti-patterns

Don’t be vague

# Bad — which service? Which data? What format?
"Get me some customer data"

# Good — explicit service, scope, format
"Query the payment service for all customers with active subscriptions.
Return customer_id, email, plan_name, and monthly_amount."

Don’t chain unrelated tasks

One task, one goal. Need two unrelated things done? Create two tasks.

# Bad — two unrelated tasks in one prompt
"Send a welcome email AND update the CRM AND check the weather"

# Good — one focused task
"Send a welcome email to user_123 using the new_signup template
from the email service. Include name and plan tier in template variables."

Don’t assume context

Ploton doesn’t remember previous tasks unless that knowledge is encoded through execution training. Each prompt needs to be self-contained.

# Bad — references "the file" with no context
"Upload the file to Drive"

# Good — fully specified
"Upload the PDF at https://your-app.com/invoices/inv_456.pdf
to user_123's cloud storage in the 'Invoices' folder. Create
the folder if it doesn't exist."

Don’t embed credentials in prompts

Never put API keys, passwords, or tokens in prompt text. Ploton handles credentials through its OAuth system and tool configuration.

# Bad — credential in the prompt
"Connect to the CRM with API key hk_abc123 and fetch contacts"

# Good — Ploton handles auth via user_id
"Fetch all contacts from user_123's CRM account created this month"

Testing prompts

Use mode: "test" to validate a prompt without executing it. This lets you check that Ploton picks the right tools and plans the right steps.

curl -X POST https://api.ploton.ai/v1/tasks \
  -H "Authorization: Bearer $PLOTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Send a message to the #general channel in the team chat saying hello",
    "user_id": "user_123",
    "mode": "test"
  }'
{
  "id": "task_test_abc",
  "status": "complete",
  "mode": "test",
  "validation": {
    "tools_selected": ["chat"],
    "planned_steps": ["authenticate", "resolve_channel", "post_message"],
    "estimated_duration_ms": 800
  }
}

Test mode runs tool selection and workflow planning without making real API calls to external services. Iterate on phrasing here before deploying to production.

Next steps

Previous Webhooks Next Registering Custom Tools