OI Agents FAQ and Troubleshooting¶
What is an Agent in Agentic Workflows?
An Agent is a configurable unit that wraps an AI model, system prompt, memory scope, and tools. It can act autonomously and is assigned to tasks within a workflow.
How do I connect tasks together in a workflow?
Use the visual canvas to draw arrows (handoffs) between tasks. The output of one task becomes the input for the next. You can define branching, sequential, or conditional flows.
What is the role of a Tool in a workflow?
Tools allow agents to take actions—such as calling APIs, reading files, or querying a database. You assign tools to tasks, and the agent decides when and how to use them.
What is MCP and how do I use it?
MCP (Model Context Protocol) enables integration with external systems like CRMs, ERPs, or vector DBs. You can register MCP servers and assign them to tasks for contextual data access and service orchestration.
How do I test and debug a workflow before deployment?
Click Run in the canvas to test in development mode. Use the logs and traces to observe how agents execute, inspect inputs/outputs, and refine logic before deploying.
How do I deploy a workflow?
After validation, click Deploy. Workflows can be triggered via API or UI, and deployments include status tracking, rollback history, and execution logs.
Can I reuse agents or tools across multiple workflows?
Yes. Agents and tools are reusable resources. You can manage them in the library and assign them to multiple workflows without duplication.
What’s the difference between a Task and a Workflow?
A Workflow is a complete process composed of multiple Tasks. Each Task is a node in the workflow assigned to a specific agent, tools, and logic.
What is RAG in OI Agents?
Retrieval-Augmented Generation (RAG) combines AI generation with real-time retrieval from a knowledge base. It ensures more accurate, context-aware responses.
How do I create a Knowledge Base?
Navigate to the Knowledge Base section, upload documents, or link data sources. The system will automatically chunk and embed content for retrieval during bot interactions.
Document stuck at 'Processing' in Knowledge Base
What You See¶
- A document has been uploaded to a Knowledge Base.
- Its status remains "Processing" and never changes to "Processed".
Why It Happens¶
- The embedding model inference service is unavailable or misconfigured.
- The Doc Processing Max Tokens setting exceeds the selected embedding model's capacity.
How to Fix It¶
- Lower the Doc Processing Max Tokens value in the Knowledge Base settings and reprocess the document.
- Verify that the embedding model is correctly configured in OI Agents.
- If everything appears correct, contact your administrator to check the embedding model service status in OICM.
How do I create a RAG bot?
Go to Bot Studio → ➕ New Bot → select a model → link one or more Knowledge Bases → assign a prompt → test and debug in real time.
No models appear in the dropdown when training a bot
What You See¶
- You open a bot for training/editing.
- The Model dropdown is empty or shows no selectable options.
Why It Happens¶
- No models have been registered or made available to your account/workspace.
- For organization bots, the administrator has not enabled any models.
How to Fix It¶
- Organization Bots: Contact your administrator and request that at least one model be enabled for your workspace or the specific bot.
- Personal Bots: Go to Model Registry, add/register a model, then return to the bot and select it from the dropdown.
Can I use multiple Knowledge Bases in one bot?
Yes. In the Knowledge tab, click Add Knowledge multiple times to link as many Knowledge Bases as needed. The system will aggregate retrieved content from all linked KBs before generation.
How do I integrate my bot with external systems?
Use the bot’s dedicated API endpoints for starting conversations and receiving streaming responses. You can embed the bot into web applications or call it from backend services.
What’s the difference between Bot Studio and Agentic Workflows?
- Bot Studio: Focused on building RAG-based conversational bots with knowledge bases and prompts.
- Agentic Workflows: General-purpose orchestration platform for multi-step, multi-agent automation with tools, branching logic, and external system integration.