Skip to main content
MeshAgent provides two built-in TaskRunners that you can use instantly in any MeshAgent room. These agents extend the TaskRunner class and add planning, reasoning, and optional tool use capabilities. The two TaskRunners are meshagent.planner which generates a text response from a prompt and meshagent.schema_planner which generates a structured JSON response that matches a schema you define. These are ideal for quick experiments, testing tools, or running simple one-turn tasks that don’t need conversation context. You can call them via:
  • MeshAgent CLI: Run tasks directly from your terminal
  • Language SDKs: Use the room.agents.ask() method (e.g. in Python, JavaScript, etc.)
  • MeshAgent Studio: Use the Run Task… menu directly from your Room (Planner only)

​
Setup

If you plan to call the built-in TaskRunners from the MeshAgent CLI, no setup is required beyond signing in with:
bash
meshagent setup
If you want to call them from a language SDK (Python, JS, etc.), create and activate an API key, then export it so the SDK can authenticate:
bash
# Create and activate a key — this stores it for CLI and prints it once
meshagent api-key create my-dev-key activate

# For SDK samples, export it as an environment variable
export MESHAGENT_API_KEY="paste-the-key-here"

​
meshagent.planner

The Planner is a TaskRunner that uses structured planning and returns a text response. You provide it a prompt (and optionally tools), and it yields a text response using a fixed output schema: {"result":"<text>"}. This makes it a great choice for single-turn prompts or testing how your custom tools behave with an agent.

​
Running meshagent.planner programmatically

 meshagent agents ask \
 --room test \
 --agent meshagent.planner \
 --input '{"prompt": "Write a product description for a bluetooth speaker"}'
Note: When you run this from the MeshAgent CLI, it automatically connects to the room and waits for the agent to join before sending the task. If you’re calling the agent from a language SDK (like Python or JavaScript), you might occasionally see an error such as “agent not in room” if the TaskRunner hasn’t joined yet. In that case, just wait a few seconds and retry once the agent is connected.

​
Running meshagent.planner from MeshAgent Studio

You can also run the meshagent.planner directly from the MeshAgent Studio UI.
  1. From the Studio, start a new session and go to the room
  2. Click the menu in the upper left and select Run Task…
  3. Choose the Generic TaskRunner agent (this is the meshagent.planner)
  4. Optionally Add Tools to the agent. These can be built-in MeshAgent tools like the UI tools, or other tools you have called into your room to test.
  5. Click Continue. The agent will determine what additional details to collect before proceeding with the task and returning a response.
When tools are added, the Planner will determine which tools to use, gather inputs, and produce the final text response in the same {"result": ...} shape. This provides a simple way to validate your custom tools interactively and see what type of text response an agent might generate when it uses your tool.

​
meshagent.schema_planner

The Schema Planner works like the Planner, but returns a user defined structured output instead of text. You define a JSON Schema describing the desired response, and the agent ensures its output matches that schema. This is especially useful when you need predictable, machine-readable results (e.g., generating product data, form fields, or structured configs).

​
Running meshagent.schema_planner programmatically

REQUEST=$(cat <<'JSON'
{
    "prompt": "Create a product listing for a bluetooth speaker",
    "output_schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["title", "price", "features", "description"],
        "properties": {
        "title": {"type": "string"},
        "price": {"type": "number"},
        "features": {"type": "array", "items": {"type": "string"}},
        "description": {"type": "string"}
        }
    }
}
JSON
)

meshagent agents ask \
--room test \
--agent meshagent.schema_planner \
--input "$REQUEST"
Note: You can’t currently use the Schema Planner directly from the Studio UI because it requires you to define a full JSON schema as input.
Use the CLI or API to test it instead.

​
Why use these built-ins?

  • Prototype fast: Try ideas without writing a custom agent.
  • Validate tools: Attach your tools and toolkits to see how well an agent understand them and when it invokes them.
  • Great for one-off tasks: Ideal when you don’t need context from a multi-turn conversation.

​
Next Steps

Dive Deeper into TaskRunners Learn how to deploy agents with MeshAgent