Skip to main content

Chapter 21: Crafting Effective Strategies

TL;DR​

  • A Strategy is the set of instructions you give an agent that guides its long-term behavior. It's advanced prompt engineering for Worka agents.
  • You define a strategy when you call the upsert_agent tool.
  • Narrative Strategy: Use the description field to give the agent a detailed persona and high-level instructions in natural language. Tell it who it is and how it works.
  • State-Based Strategy: Use the rules array to provide more structured, IF-THEN-style instructions for specific, predictable situations.
  • Effective agents use a combination of both.

Simply creating an agent and giving it a prompt is not enough to build a robust and reliable AI workflow. To get the best results, you need to provide the agent with a Strategy.

A strategy is the core guidance that shapes how an agent interprets goals and makes plans. It's how you steer the AI's reasoning process. In Worka, you craft a strategy by populating the fields of the upsert_agent tool, primarily the description and rules.

Narrative Strategy: The Agent's Persona​

The description field is where you define the agent's persona using natural language. This is a powerful way to give the agent a high-level methodology, a personality, and a set of constraints. A good narrative strategy goes beyond a simple job title.

Bad Example: "description": "You are a helpful assistant."

This is too generic. The agent has no specific guidance on how to behave.

Good Example for a "Code Refactoring Agent":

{
  "name": "code-refactor-agent",
  "description": "You are a senior software engineer specializing in refactoring legacy code. Your primary goal is to improve code quality without changing its external behavior. You are cautious and methodical. You prefer to make many small, verifiable changes rather than one large one. You always run the test suite after every single change you make to ensure you have not introduced a regression."
}

This description gives the agent clear instructions on its persona (senior engineer), its goal (improve quality), its constraints (without changing behavior), and its methodology (small changes, run tests).

State-Based Strategy: The Agent's Rules​

While the narrative strategy sets the overall approach, the rules array allows you to provide more structured, IF-THEN style guidance for specific situations you can anticipate.

A rule is an object with a name and content that the agent will consider during its planning phase.

Example Rule for our "Code Refactoring Agent":

Let's say we want to give it a specific instruction for what to do when a test fails.

{
  "name": "code-refactor-agent",
  "description": "... (from above) ...",
  "rules": [
    {
      "name": "On Test Failure Rule",
      "content": "IF a test fails after you have made a code change, your immediate next step is to revert the change you just made. DO NOT attempt to fix the test or the code. After reverting, re-run the tests to ensure they pass. Only then should you re-evaluate the original problem and form a new plan."
    }
  ]
}

This rule gives the agent an explicit, non-negotiable algorithm to follow in a predictable but critical situation, making its behavior much more reliable.

Combining Strategies​

The most effective agents are built by combining these two approaches. The narrative strategy sets the broad persona and philosophy, while the state-based rules provide guardrails and specific instructions for common scenarios. Mastering the art of crafting these strategies is the key to unlocking the full potential of the Worka orchestrator.