Create and Orchestrate an Agent

On desktop, Agent Studio (/app/apps/{agent_id}) uses a two-column layout for orchestration and live preview:

• Orchestration Editor: Configure the model, system prompt, variables, knowledge bases, tools, and runtime settings.
• Live Preview Panel: Test draft-agent conversations without leaving the page or publishing changes.
• Top Toolbar: Access Agent metadata, publication status (Draft or Published), Embed, and Agent Settings.

On phones, the side-by-side preview is hidden so the editor stays full-width. Select Preview in the toolbar to open the chat in a full-screen, drawer-like overlay; close it to return to editing.

Create an Agent

1. Navigate to Apps, select Create App > Agent.
2. Fill in the name (1-100 characters) and description (up to 500 characters).
3. Select an owning team.
4. On the Agent Studio orchestration page, select Agent Settings in the top-right corner, choose the model, and configure the name, icon, opening message, suggested questions, and visibility.
5. Visibility defaults to Private (only the creator can access it); switch it to Team as needed.

Max Iterations is the Agent setting max_iterations: how many tool-call rounds an Agent may run within a single reply. It defaults to 5 and accepts 1-200 (server-validated). Set it too low and complex tasks end early with max_iterations_reached; set it too high and a repeatedly failing tool can burn a lot of tokens.

Write the Prompt and Variables

1. In the Prompt, specify the role, task, constraints, tool usage conditions, and failure handling.
2. Type { to open the variable selector. {query} is the current user message.
3. In Variables, add user input fields. Variable names can be up to 50 characters; you can configure the display name, required, hidden, default value, options, numeric range, or maximum length.
4. Fill in the variables in the preview on the right and confirm the substitution result.

Configure Knowledge Base and RAG

1. In the Knowledge Base area, select Add.
2. Select a Knowledge Base and a vector, fulltext, or hybrid retrieval mode.
3. Set Top K (1-100, default 5) and the threshold (0-1, default 0.3).
4. Optionally enable Rerank to improve recall precision.
5. Set the overall RAG mode: Off, Auto, or Agentic.

Knowledge base ordering is defined by the knowledge_base_configs list and can be adjusted when editing the agent; this order is applied when the agent retrieves context. Without a knowledge-base association, the backend normalizes persisted rag_mode to off and the editor hides the RAG mode selector; the selector appears after a knowledge base is attached.

Add Tools and Capabilities

In the Tools area, select built-in tools, custom tools, MCP, or Skills.

When a tool shows "Configuration needed", go to Capabilities first to complete the credentials. Custom tools are created and tested in Capabilities, then enabled per agent.

Configure Attachments, Media, and Memory

Before enabling attachments, image generation, video generation, or cross-session memory, turn on the corresponding capabilities in the Agent Orchestration:

Media generation covers images and videos only (there is no audio/TTS generation). Turning on image or video generation injects the generate_image / generate_video tool into the model and calls the team-authorized model of that kind; with the switch off the model never sees those tools.

On context: long conversations are compressed with a single summary — once a request exceeds the trigger budget, the older history is replaced by one generated summary while the recent stretch stays verbatim. That summary is scoped to the current conversation and is not cross-conversation memory, which is a separate persisted entity/relation graph.

For full configuration options, see Attachments and Media and Memory and Context.

Set Visibility and Publish

1. Choose Private or Team visibility.
2. Select Publish. After publishing the status becomes published and the agent can receive messages.
3. After publishing, you can open the Public Page, Embed, and Access API.

Save, Debug, and Publish

1. Select Save. Validation errors list the specific fields.
2. In Debug & Preview, send questions that cover both normal and failure paths.
3. When tools are present, verify tool parameters, failure prompts, and max-iteration termination behavior.
4. Select Publish.

To hide the generated files list below assistant messages, turn on Hide Artifact List in Agent Settings. It is off by default; enabling it hides the list without deleting the generated files.

Monitoring and Statistics

Each Agent has a dedicated Monitor page (/app/apps/{agent_id}/monitor), accessible via Monitor in the Agent sidebar. The page displays overview cards, usage trends, tool call distribution, Execution Health, First Token Latency, and User Interventions across 24h, 7d (default), and 30d.

Data is backed by three read-only endpoints (GET /api/v1/agents/{agent_id}/stats*, period: 24h, 7d, 30d, all):

API Endpoints

Admin endpoints live under /api/v1/admin/agents and require admin:app:* permissions.

// List all agents (filter by status, visibility, team, creator, search)
const agents = await api.get("/api/v1/admin/agents", { params: { status: ["published"] } });

// Create agent for a team
const agent = await api.post("/api/v1/admin/agents", {
    name: "Support Agent",
    team_id: "team-123",
    model_id: "model-456",  // TeamModel ID (a team-granted model)
    system_prompt: "You are a helpful assistant.",
    rag_mode: "agentic"
});

// Update agent (PUT, not PATCH)
const updated = await api.put(`/api/v1/admin/agents/${agent_id}`, {
    name: "Support Agent v2"
});

// Publish / unpublish / duplicate
await api.post(`/api/v1/admin/agents/${agent_id}/publish`);
await api.post(`/api/v1/admin/agents/${agent_id}/unpublish`);
await api.post(`/api/v1/admin/agents/${agent_id}/duplicate`);

// Get agent statistics (period: 24h, 7d, 30d, all)
const stats = await api.get(`/api/v1/agents/${agent_id}/stats`, { params: { period: "30d" } });

For full API details, see Agents API.

Best Practices

Agent Design

• ✅ Write clear, specific system prompts

• ✅ Test agents thoroughly before deployment

• ✅ Use appropriate models for tasks

• ✅ Enable RAG for factual accuracy

• ✅ Monitor usage via the statistics endpoints

• ✅ Collect user feedback and iterate

• ❌ Use vague system prompts

• ❌ Deploy untested agents

• ❌ Use expensive models for simple tasks

• ❌ Ignore error rates

• ❌ Forget to monitor costs

Performance

• ✅ Use streaming for better UX

• ✅ Optimize knowledge base search

• ✅ Set appropriate timeouts

• ❌ Use synchronous processing for long tasks

• ❌ Overload agents with too many knowledge bases

• ❌ Set very high max_tokens

Troubleshooting

Agent Not Responding

1. Check agent status: Verify it's published; check model availability.
2. Check model configuration: Verify API key is valid; test model connectivity; check rate limits.
3. Check knowledge bases: Verify they're indexed; confirm search works.
4. Check audit logs: Filter by resource type agent and the matching resource ID.

Poor Response Quality

1. Review system prompt: Make instructions clearer; add examples; set boundaries.
2. Improve knowledge base: Add more relevant documents; update outdated content; improve chunking strategy.
3. Enable Agentic RAG: Lets the agent decide when to retrieve, improving factual grounding.

High Costs

1. Review usage: Check GET /api/v1/agents/{agent_id}/stats for token usage and conversation counts; identify high-usage agents.
2. Optimize prompts: Shorter system prompts; reduce context length; use cheaper models for simple tasks.

FAQ

• Empty model list: The team has no authorized chat model, or the model is disabled.
• Tools are not called: Check the model's function-calling capability, whether the tool is enabled, and whether the prompt defines the calling conditions.
• Publish fails: Confirm you have the publish permission, and that the model, variable references, and capability configuration are valid.
• Public page inaccessible: Confirm the Agent is published; private/team visibility is still affected by sign-in and team access control.

Limitations and Roadmap