Agent Transitions

Posted on

Agent Transitions – The Complete Guide to Autonomous AI Execution in Agentic Nets

The Agent transition is the most powerful and flexible transition type in Agentic Nets. While LLM transitions execute single prompts and return responses, Agent transitions enable autonomous, iterative AI execution – agents that can reason, plan, execute multiple steps, and dynamically discover where to read from and write to based on natural language instructions.

In this comprehensive guide, we’ll explore every capability of Agent transitions:

  • Natural language instructions – literal, expression-based, or template-interpolated
  • Dynamic discovery – agents discover presets/postsets from NL context (presets are OPTIONAL)
  • Token generation – agents create NEW tokens rather than transforming existing ones
  • Multi-postset routing – intelligent routing to different output places
  • Iteration control – configurable maxIterations for bounded execution
  • Data enrichment – add computed fields and derived data
  • Classification patterns – route tokens based on AI analysis
  • Aggregation patterns – combine data from multiple tokens

What Makes Agent Transitions Different?

Unlike other transition types, Agent transitions are autonomous. They don’t just execute a single operation – they:

  1. Understand intent from natural language instructions
  2. Plan execution by decomposing complex tasks
  3. Execute iteratively using tool calls until the task is complete
  4. Create new tokens rather than just transforming input data
  5. Handle edge cases intelligently without explicit error handling

This makes Agent transitions ideal for tasks that require reasoning, judgment, or complex decision-making.

Anatomy of an Agent Transition Inscription

Every Agent transition inscription follows this structure:

{
  "id": "t-my-agent-task",
  "kind": "agent",
  "mode": "SINGLE",

  "presets": {
    "input": {
      "placeId": "task-queue",
      "host": "myModel@localhost:8080",
      "arcql": "FROM $ LIMIT 1",
      "take": "FIRST",
      "consume": true
    }
  },

  "postsets": {
    "output": { "placeId": "results-queue", "host": "myModel@localhost:8080" },
    "audit": { "placeId": "audit-log", "host": "myModel@localhost:8080" }
  },

  "action": {
    "type": "agent",
    "nl": "Process the task and create appropriate output tokens. Log actions to audit.",
    "maxIterations": 10
  },

  "emit": [
    { "to": "output", "from": "@response", "when": "success" },
    { "to": "audit", "from": "@response", "when": "success" }
  ]
}

Key differences from LLM transitions:

  • kind: "agent" – identifies this as an Agent transition (NOT “task” like LLM)
  • action.type: "agent" – specifies the Agent action handler
  • presets are OPTIONAL – agents can discover from NL instruction
  • postsets are REQUIRED – agents need defined output locations
  • maxIterations – bounds the agent’s autonomous execution loop

NL Instruction Patterns

Agent transitions support three ways to specify the natural language instruction:

1. Literal Instructions

Direct text in the inscription – useful for fixed, reusable agent tasks:

{
  "action": {
    "type": "agent",
    "nl": "Create a simple token with fields 'message' set to 'Hello from Agent' and 'timestamp' set to current time. Output to the 'output' place.",
    "maxIterations": 10
  }
}

2. Expression-Based Instructions

Read the instruction from token data using @input.data.instruction:

{
  "action": {
    "type": "agent",
    "nl": "@input.data.instruction",
    "maxIterations": 10
  }
}

With an input token like:

{
  "instruction": "Generate a summary token with 'status' set to 'processed' and 'source' set to 'input-token'",
  "taskId": "TASK-001"
}

This pattern enables token-driven agents where the task itself is data.

3. Template Interpolation

Combine fixed text with token data using ${...} syntax:

{
  "action": {
    "type": "agent",
    "nl": "Process order ${input.data.orderId} for customer ${input.data.customerName}. Amount: ${input.data.amount}. Create a receipt token with 'orderId', 'customer', 'amount', and 'status' set to 'completed'.",
    "maxIterations": 10
  }
}

With an input token like:

{
  "orderId": "ORD-12345",
  "customerName": "John Doe",
  "amount": "150.00"
}

The instruction becomes: “Process order ORD-12345 for customer John Doe. Amount: 150.00. Create a receipt token…”

Agent Token Generation

Unlike Pass/Map/HTTP transitions that route or transform existing tokens, Agent transitions create NEW tokens. This is a fundamental difference:

Transition Type Token Behavior
Pass Routes existing token to postset
Map Transforms existing token via template
HTTP Routes HTTP response as token
LLM Routes LLM response as token
Agent Creates NEW tokens from scratch

Creating Multiple Tokens

Agents can create multiple tokens in a single execution:

{
  "action": {
    "type": "agent",
    "nl": "Create THREE separate tokens in the 'output' place: 1) {\"item\": \"apple\", \"quantity\": 5} 2) {\"item\": \"banana\", \"quantity\": 3} 3) {\"item\": \"orange\", \"quantity\": 7}",
    "maxIterations": 15
  }
}

Structured Token Generation

Agents can generate tokens with complex nested structures:

{
  "action": {
    "type": "agent",
    "nl": "Create a token with the following structure: 'orderId': 'ORD-999', 'customer': {'name': 'Jane Smith', 'email': 'jane@example.com'}, 'items': [{'product': 'Widget', 'qty': 2}], 'total': 59.99, 'status': 'pending'",
    "maxIterations": 10
  }
}

Agent with Presets (Optional Input)

While presets are optional for agents, using them enables powerful input processing patterns:

Input Consumption Pattern

{
  "id": "t-agent-process",
  "kind": "agent",
  "presets": {
    "input": {
      "placeId": "raw-data",
      "host": "myModel@localhost:8080",
      "arcql": "FROM $ LIMIT 1",
      "take": "FIRST",
      "consume": true
    }
  },
  "postsets": {
    "output": { "placeId": "processed-data", "host": "myModel@localhost:8080" }
  },
  "action": {
    "type": "agent",
    "nl": "Read the rawData from the input token, process it (add a summary field), and create a processed token in the output place. Include the original priority.",
    "maxIterations": 10
  },
  "emit": [{ "to": "output", "from": "@response", "when": "success" }]
}

Multiple Preset Pattern

Agents can read from multiple input places and combine data:

{
  "id": "t-agent-combine",
  "kind": "agent",
  "presets": {
    "orders": {
      "placeId": "orders-queue",
      "host": "myModel@localhost:8080",
      "arcql": "FROM $ LIMIT 1",
      "take": "FIRST"
    },
    "customers": {
      "placeId": "customers-queue",
      "host": "myModel@localhost:8080",
      "arcql": "FROM $ LIMIT 1",
      "take": "FIRST"
    }
  },
  "postsets": {
    "output": { "placeId": "combined-data", "host": "myModel@localhost:8080" }
  },
  "action": {
    "type": "agent",
    "nl": "Combine order data from 'orders' preset with customer data from 'customers' preset. Create a combined token with orderId, customerName, customerTier, and orderAmount.",
    "maxIterations": 15
  },
  "emit": [{ "to": "output", "from": "@response", "when": "success" }]
}

Multi-Postset Routing

Agents can intelligently route tokens to different output places based on their analysis:

Conditional Routing Pattern

{
  "id": "t-agent-route",
  "kind": "agent",
  "presets": {
    "input": {
      "placeId": "requests",
      "host": "myModel@localhost:8080",
      "arcql": "FROM $ LIMIT 1",
      "take": "FIRST"
    }
  },
  "postsets": {
    "approved": { "placeId": "approved-requests", "host": "myModel@localhost:8080" },
    "rejected": { "placeId": "rejected-requests", "host": "myModel@localhost:8080" }
  },
  "action": {
    "type": "agent",
    "nl": "Evaluate request ${input.data.requestId} with amount ${input.data.amount}. If amount > 100, create a token in 'approved' with status='approved'. Otherwise, create a token in 'rejected' with status='rejected'. Include the original requestId and amount in the output token.",
    "maxIterations": 10
  },
  "emit": [
    { "to": "approved", "from": "@response", "when": "success" },
    { "to": "rejected", "from": "@response", "when": "success" }
  ]
}

Fan-Out Pattern

Create tokens in multiple places simultaneously:

{
  "id": "t-agent-fanout",
  "kind": "agent",
  "presets": {
    "input": { "placeId": "events", "host": "myModel@localhost:8080", "arcql": "FROM $ LIMIT 1", "take": "FIRST" }
  },
  "postsets": {
    "audit": { "placeId": "audit-log", "host": "myModel@localhost:8080" },
    "notification": { "placeId": "notifications", "host": "myModel@localhost:8080" },
    "archive": { "placeId": "archive", "host": "myModel@localhost:8080" }
  },
  "action": {
    "type": "agent",
    "nl": "Process event ${input.data.eventId} of type ${input.data.eventType}. Create THREE tokens: 1) In 'audit' place with eventId and action='logged' 2) In 'notification' place with eventId and action='notified' 3) In 'archive' place with eventId and action='archived'",
    "maxIterations": 15
  },
  "emit": [
    { "to": "audit", "from": "@response", "when": "success" },
    { "to": "notification", "from": "@response", "when": "success" },
    { "to": "archive", "from": "@response", "when": "success" }
  ]
}

Advanced Agent Patterns

Data Enrichment

Agents excel at adding computed or derived fields to data:

{
  "action": {
    "type": "agent",
    "nl": "Enrich product ${input.data.productId}: ${input.data.name}, price: ${input.data.basePrice}. Add fields: 'description' (generate marketing copy), 'category' (determine product category), 'priceWithTax' (calculate with 10% tax), and 'inStock' (set to true). Include all original fields.",
    "maxIterations": 10
  }
}

Classification

Route items based on AI-driven classification:

{
  "id": "t-agent-classify",
  "kind": "agent",
  "presets": {
    "input": { "placeId": "tickets", "host": "myModel@localhost:8080", "arcql": "FROM $ LIMIT 1", "take": "FIRST" }
  },
  "postsets": {
    "urgent": { "placeId": "urgent-tickets", "host": "myModel@localhost:8080" },
    "normal": { "placeId": "normal-tickets", "host": "myModel@localhost:8080" },
    "low": { "placeId": "low-priority-tickets", "host": "myModel@localhost:8080" }
  },
  "action": {
    "type": "agent",
    "nl": "Classify support ticket ${input.data.ticketId}: '${input.data.subject}'. Based on urgency, create token in appropriate place: 'urgent' for critical issues, 'normal' for standard issues, 'low' for minor issues. Include ticketId, subject, and 'priority' field with classification.",
    "maxIterations": 10
  },
  "emit": [
    { "to": "urgent", "from": "@response", "when": "success" },
    { "to": "normal", "from": "@response", "when": "success" },
    { "to": "low", "from": "@response", "when": "success" }
  ]
}

Aggregation

Combine data from multiple tokens into a summary:

{
  "id": "t-agent-aggregate",
  "kind": "agent",
  "presets": {
    "items": {
      "placeId": "line-items",
      "host": "myModel@localhost:8080",
      "arcql": "FROM $ LIMIT 10",
      "take": "ALL"
    }
  },
  "postsets": {
    "summary": { "placeId": "order-summaries", "host": "myModel@localhost:8080" }
  },
  "action": {
    "type": "agent",
    "nl": "Read all items from the 'items' place. Calculate: 1) totalItems (sum of all quantities) 2) totalValue (sum of quantity * price for each item) 3) itemCount (number of different products). Create a summary token with these calculated fields.",
    "maxIterations": 15
  },
  "emit": [{ "to": "summary", "from": "@response", "when": "success" }]
}

Iteration Control

The maxIterations parameter controls how many tool calls the agent can make before stopping. This provides:

  • Cost control – limits API calls and compute resources
  • Timeout safety – prevents infinite loops
  • Predictability – bounded execution time
{
  "action": {
    "type": "agent",
    "nl": "Complete this complex multi-step task...",
    "maxIterations": 50  // Default is 50 if not specified
  }
}

Guidelines:

  • Simple tasks: 5-10 iterations
  • Medium complexity: 10-20 iterations
  • Complex multi-step tasks: 20-50 iterations

Execution Characteristics

Agent transitions have unique execution characteristics compared to other transition types:

Aspect Agent Transition Other Transitions
Execution Time 30-60+ seconds (iterative) 1-5 seconds
API Calls Multiple (per iteration) Single
Output NEW tokens created Existing tokens routed/transformed
Determinism Non-deterministic Deterministic
Presets Required No (optional) Yes

Error Handling and Edge Cases

Agent transitions handle edge cases gracefully:

Empty NL Instructions

Agents handle empty or minimal instructions by doing nothing (no tokens created):

{
  "action": {
    "type": "agent",
    "nl": "",  // Empty - agent will not produce output
    "maxIterations": 5
  }
}

Special Characters

Agents handle quotes, unicode, and special characters in instructions:

{
  "action": {
    "type": "agent",
    "nl": "Create a token with message: \"Hello, World!\" and note: 'This has \"quotes\" and unicode: \u2603'",
    "maxIterations": 10
  }
}

Nested Input Data

Agents can process deeply nested JSON structures:

{
  "action": {
    "type": "agent",
    "nl": "Parse the nested 'order' JSON from input. Extract orderId, customerName, totalItems (count), and shippingMethod. Create a flattened summary token.",
    "maxIterations": 10
  }
}

Best Practices

1. Be Specific in Instructions

Clear, specific instructions produce better results:

// ✅ Good: Specific instruction with expected output
"nl": "Create a token with fields: 'orderId' (the input orderId), 'status' (set to 'processed'), 'processedAt' (current timestamp)"

// ❌ Bad: Vague instruction
"nl": "Process the order"

2. Name Postsets Clearly

Use descriptive postset names that match the instruction:

// ✅ Good: Postset names match instruction
"postsets": { "approved": {...}, "rejected": {...} }
"nl": "Route to 'approved' or 'rejected' based on amount..."

// ❌ Bad: Generic names
"postsets": { "output1": {...}, "output2": {...} }

3. Set Appropriate Iteration Limits

Match maxIterations to task complexity:

// Simple token creation: low limit
"maxIterations": 5

// Multi-step processing: medium limit
"maxIterations": 15

// Complex aggregation: higher limit
"maxIterations": 30

4. Handle Non-Determinism

Agent execution is non-deterministic. Design agentic processes that handle variable output:

  • Use downstream transitions to validate/normalize agent output
  • Include error handling postsets for unexpected cases
  • Log agent actions to audit places for debugging

Complete Example: Support Ticket Pipeline

Here’s a complete example showing an Agent transition in a realistic agentic process:

{
  "id": "t-ticket-processor",
  "kind": "agent",
  "mode": "SINGLE",

  "presets": {
    "ticket": {
      "placeId": "incoming-tickets",
      "host": "support-model@localhost:8080",
      "arcql": "FROM $ WHERE $.status==\"new\" LIMIT 1",
      "take": "FIRST",
      "consume": true
    }
  },

  "postsets": {
    "urgent": { "placeId": "urgent-queue", "host": "support-model@localhost:8080" },
    "normal": { "placeId": "normal-queue", "host": "support-model@localhost:8080" },
    "spam": { "placeId": "spam-archive", "host": "support-model@localhost:8080" },
    "audit": { "placeId": "processing-log", "host": "support-model@localhost:8080" }
  },

  "action": {
    "type": "agent",
    "nl": "Analyze support ticket ${ticket.data.id}: Subject: '${ticket.data.subject}', Body: '${ticket.data.body}'. Classify the ticket: 1) If it mentions system outage, data loss, or security issues, route to 'urgent' with priority='critical' 2) If it's a legitimate support request, route to 'normal' with priority='standard' 3) If it appears to be spam or automated, route to 'spam' with priority='none'. Also create an audit log entry in 'audit' with ticketId, classification, and reasoning. Include all original ticket fields in the output.",
    "maxIterations": 10
  },

  "emit": [
    { "to": "urgent", "from": "@response", "when": "success" },
    { "to": "normal", "from": "@response", "when": "success" },
    { "to": "spam", "from": "@response", "when": "success" },
    { "to": "audit", "from": "@response", "when": "success" }
  ]
}

Summary

Agent transitions bring autonomous AI capabilities to Agentic Nets. They enable:

  • Token-driven agentic processes where tasks are data
  • Intelligent routing based on AI analysis
  • Data enrichment with computed and derived fields
  • Complex aggregation from multiple sources
  • Flexible classification for dynamic routing

Use Agent transitions when your agentic process requires reasoning, judgment, or multi-step autonomous execution that would be impractical to code explicitly.

Leave a Reply

Your email address will not be published. Required fields are marked *