Agents
Agents are the core building blocks of an agentic system. An agent packages instructions, context and capabilities to solve a focused task. Each edit creates a new version automatically, letting you control when changes go live inside Meshes.
Quick Reference
Below each group lists its fields with a concise purpose and guidance (when to adjust, interactions, impacts, tips).
Metadata
| Field | Purpose | Guidance |
|---|---|---|
| Name | Human readable identifier | Displayed in lists and traces to identify this agent. |
| Description | High level purpose & scope | Provide a concise overview of the agent's role and responsibilities. |
Identity & Task Instructions
| Field | Purpose | Guidance |
|---|---|---|
| Identity | Persona framing | Change to steer tone or expertise; interacts with Task Instructions for behavioral grounding. |
| Task Instructions | Core operational directives | Detailed instructions describing the agent's expected behavior and interactions. |
Input Schema
| Field | Purpose | Guidance |
|---|---|---|
| Input Schema | Structure of incoming messages | Define the expected format and content of messages sent to the agent. See Message Schemas for more information. |
Model Complexity
| Field | Purpose | Guidance |
|---|---|---|
| Model Complexity | Signals routing choice | Raise when outputs need deeper reasoning; interacts with Model Set rules & cost; overestimating increases latency & spend. |
User Interaction Flags
| Field | Purpose | Guidance |
|---|---|---|
| Send thinking messages | Expose reasoning snippets | Allows the agent to send thinking messages directly to the user to expose the agent's reasoning. Enable for transparency or user feedback. If displayed in a UI, consider collapsing but allowing user to expand. |
| Send progress messages | Show milestone updates | Allows the agent to send progress messages directly to the user. Enable for long running agents operating in a context where user progress updates can be displayed. |
| Ask questions to the user | Allow clarification | Allows the agent to ask questions to the user for clarification. Enable when tasks may require user input; interacts with conversation flow & latency; excessive questions may frustrate users. |
| Include conversation history | Preserve multi-turn context | Enables the agent to access prior conversation history. Experiment with this and using memory slots. Long conversation histories can degrade performance and increase costs, but are simpler to implement. Explicitly modeled memory is more complex, but can control context length. |
MCP Connections
| Field | Purpose | Guidance |
|---|---|---|
| MCP Connections | External tool access set | MCP Connections available to the agent. Limit to only essential tools for security and to preserve context window. |
Memory Slots
| Field | Purpose | Guidance |
|---|---|---|
| Name | Identifier exposed to agent | The name of the memory slot. This is exposed to the agent. Choose descriptive stable names. When using the Global scope, shared names enable cross-agent access. |
| Description | What to store & when | Provide clear guidance to the agent about what information to store in this memory slot and under what circumstances. |
| Scope | Lifetime & sharing boundary | Set the lifetime and sharing boundary for this memory slot. See the Memory Slots section for details on each scope option. |
| Message Type | Structure of stored data | Provide a clear schema for data storage. Clear field names, data types and descriptions will improve performance. |
Tags
| Field | Purpose | Guidance |
|---|---|---|
| Tags | Metadata for routing & categorization | Add to influence model selection & experiments; interacts with Model Set rule matching. |
Identity & Task Instructions
Well-crafted Identity and Task Instructions are the key to an effective agent. These configurations strongly influence correctness, tone and tool usage. Keep scope narrow. Agents should have a single task to perform. If you find the task instructions growing large and unwieldy, consider if this agent should be split into multiple interacting agents.
Identity
Persona framing guiding tone & perspective. Avoid vague multi-discipline personas - specificity improves reasoning.
Task Instructions
Imperative directives for a single task or tightly related set. Prefer positive instructions (“Do …”) over negative (“Don’t …”). Review traces to refine unclear steps. Well chosen examples can improve performance.
Input Schema
Defines structured data the agent receives. Keep minimal by structuring the schema to minimize extraneous information that can confuse the agent. See Message Schemas.
Model Complexity
Signals routing decisions in Model Sets. Start at the lowest level that achieves acceptable quality; raise after trace review showing reasoning failures. Periodically audit for cost regressions.
User Interaction Flags
Enable selectively to balance transparency, latency and cost. “Thinking” output is powerful internally but rarely needed externally. Conversation history can balloon token usage - disable for stateless classification agents.
MCP Connections
Expose only the tools strictly required. Extra tools enlarge prompt/tool context and expand attack surface (prompt injection, unintended actions). Apply least privilege and review periodically.
Memory Slots
Memory slots store structured data the agent (and possibly other agents) may reuse across a conversation. Where and when a memory slot may be accessed is controlled by its scope.
Memory Slot Scopes
| Scope | Description |
|---|---|
| Global | Available to all agents in the conversation defining a slot with the same name. Useful for shared durable facts. |
| Local | Accessible only to this agent for the conversation duration. Use for storing internal hypotheses, temporary reasoning or input that should persist across requests. |
| Request | Shared across agents (same name) for the active top-level request only. Good for short-lived coordination without long retention. |
Design guidance: keep slot descriptions actionable (what to store + trigger conditions). Overly general descriptions lead to noisy, low-value memory accumulation.
Tags
Tags influence model routing and provide metadata for discovery/analytics. Curate a controlled vocabulary (e.g., domain:finance, modality:summary, complexity:high). Audit periodically to prune unused or duplicative tags that reduce clarity.
Design Guidance (Summary)
- Split large, multi-function Task Instructions into discrete agents.
- Prefer structured Input Schema fields over long free text when values are enumerable.
- Introduce validation agents rather than bloating a single agent with both generation and verification tasks.
- Keep MCP tool sets lean; remove unused tools discovered via trace analysis.
- Use request memory for ephemeral aggregation; avoid global unless cross-agent necessity is clear.
- Add tags intentionally to trigger routing or analysis - avoid ornamental tags.
Related
- Meshes – orchestrating multiple agent versions.
- Model Sets – model routing logic.
- Message Schemas – defining input/output structures.
- MCP Connections – external tool access.