Frequently Asked Questions

Answers to common questions about Agent Platform 2.0, organized by topic. Use the section headings to jump to the area most relevant to your question.

Frequently Asked Questions

Answers to common questions about Agent Platform 2.0, organized by topic. Use the section headings to jump to the area most relevant to your question.

---

Getting Started

How do I sign up for Agent Platform 2.0?

Go to ablplatform.com and click Get started. You can sign up with your email address or use Google or GitHub single sign-on. A free tier is available so you can start building agents immediately.

How do I reset my password?

Click Forgot password? on the login page and enter the email address associated with your account. You will receive a password reset link within a few minutes. If you signed up with Google or GitHub SSO, you do not have a platform password — sign in through your identity provider instead.

How do I invite team members to my workspace?

Open Settings > Team > Members and click Invite member. Enter their email address and select a role:

• Admin — Manage members, settings, and workspace-wide configuration.
• Operator — Monitor deployments, sessions, and analytics.
• Member — Build and test project resources in projects they can access.
• Viewer — Read-only access to projects and agent definitions.

Invited members receive an email with a link to join your workspace.

How do I switch between workspaces?

Click the workspace name in the top-left corner of Studio. A dropdown lists all workspaces you belong to. Select the one you want to switch to. Each workspace has its own projects, members, and billing.

Can I change my workspace name?

Yes. Go to Settings > Workspace > General and update the workspace name. This is a display name only and does not affect your workspace URL or project data.

What browser should I use?

Studio works best on the latest versions of Chrome, Edge, Firefox, and Safari. We recommend a Chromium-based browser (Chrome or Edge) for the best experience with the code editor and debugging tools.

Where do I find my projects?

After signing in, Studio opens to your Dashboard. All projects in your current workspace are listed here. Use the search bar to filter by name, or use the sidebar to browse by category.

How do I create a new agent?

1. Open an existing project or create a new one from the Dashboard by clicking New project.
2. Inside the project, click New agent.
3. Choose a starting point: Blank agent, From template, or use the Project Wizard to generate an agent from a natural-language description.
4. Give your agent a name and click Create.

How do I open the agent editor?

Click on any agent name within a project to open it. Agents without a FLOW section open in a full-page configuration panel. Agents with a FLOW section open in the visual flow editor with a configuration sidebar. You can also edit the raw ABL definition by clicking Code view in the editor toolbar.

What execution modes does an agent support?

Every agent reasons by default — you provide instructions, tools, and guardrails, and the LLM decides what to do at each turn. Optionally, you can add a FLOW section with structured steps to control the exact order of operations, branching, and data collection. Within each step, the REASONING: true/false flag controls whether the LLM reasons at that step.

Use the default reasoning mode for flexible, conversational tasks. Add a FLOW section when you need predictable, repeatable workflows. You can also combine both: use a FLOW for the main path and enable REASONING: true on specific steps that benefit from LLM flexibility.

How do I add my LLM API key?

Go to Settings > AI Configuration > LLM Providers and click Add provider. Select the provider (e.g., OpenAI, Anthropic, Azure OpenAI, Google Gemini), paste your API key, and click Validate and save. The platform will verify that the key works before saving it.

Which LLM models are supported?

Agent Platform 2.0 supports models from:

• OpenAI — GPT-4o, GPT-4o mini, o1, o3, and other chat completions models.
• Anthropic — Claude Opus, Claude Sonnet, Claude Haiku.
• Google — Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.0 Flash.
• Azure OpenAI — Any model deployed on your Azure OpenAI resource.
• Custom endpoints — Any OpenAI-compatible API via a custom base URL.

The available models update as providers release new versions. Check Settings > AI Configuration for the current list.

How do I change the default model for my agents?

Go to Settings > AI Configuration > Model assignments. Models are assigned to tiers: Powerful, Balanced, and Fast. Each agent definition specifies which tier it uses (default is Balanced). Change the model assigned to a tier and all agents using that tier will pick up the new model.

You can also override the model for a specific agent in the agent’s configuration panel under Model settings.

My API key validation fails — what should I check?

1. Copy the API key directly from the provider’s dashboard — avoid extra whitespace.
2. For Azure OpenAI, confirm the endpoint URL includes the correct deployment name and API version.
3. Confirm your API key has not expired and has sufficient quota or credits.
4. If your organization uses a network proxy or firewall, ensure outbound HTTPS traffic to the provider (e.g., api.openai.com, api.anthropic.com) is allowed.

My agent does not respond when I send a message

1. Check LLM configuration. Go to Settings > AI Configuration > LLM Providers and verify that at least one credential is active and validated.
2. Check model assignment. Ensure a model is assigned to the tier your agent uses (default: Balanced).
3. Check the trace. Open the session trace in the Test panel to see where execution stopped. Common error codes:
   • MODEL_NOT_FOUND — No model is configured for the requested tier.
   • CREDENTIAL_INVALID — The API key is expired or incorrect.
   • TIMEOUT — The LLM request timed out. Try again or switch to a faster model.

How do I use the Test panel?

Click the Test button (play icon) in the editor toolbar. This opens a chat panel where you can interact with your agent in real time. Each conversation creates a test session with a full execution trace.

How do I read a trace?

After sending a message in the Test panel, click the Trace tab to see the execution timeline. Each row represents a span:

• Agent span — The top-level execution of the agent.
• LLM span — A call to the language model, showing the prompt and response.
• Tool span — A tool invocation, showing input and output.
• Step span — An individual step in an agent’s flow.

Click any span to see its details, including timing, input/output data, and any errors.

Where can I see my usage?

Go to Settings > Billing > Usage. This page shows your current billing period, total sessions, LLM token consumption broken down by provider and model, and how much of your plan’s quota you have used.

What counts as a session?

A session is a single conversation between a user and an agent, from the first message to the end of the conversation. Test sessions in the Studio Test panel also count toward your usage. Each session is billed regardless of how many messages it contains.

How do I upgrade my plan?

Go to Settings > Billing > Plan and click Upgrade. Compare available plans and select the one that fits your usage. Plan changes take effect immediately and are prorated for the current billing period.

What happens if I exceed my plan limits?

You will receive a warning email when you reach 80% of your session or token quota. If you exceed 100%, new agent sessions will be paused until you upgrade your plan or the next billing cycle begins. Existing active sessions are not interrupted.

Where do I find the documentation?

The full documentation includes:

• Tutorials — Step-by-step guides for building your first agent.
• How-to guides — Task-oriented instructions for specific features.
• ABL language reference — Complete syntax and semantics for the agent definition language.
• API reference — REST API documentation for programmatic access.

Is there a community forum?

Yes. Join the Agent Platform 2.0 community to ask questions, share agent templates, and connect with other builders.

How do I contact support?

• In-app support: Click the Help button (question mark icon) in the bottom-right corner of Studio to open a support chat.
• Email: Send a message to [e-mail].
• Enterprise customers: Use your dedicated Slack channel or contact your account manager.

For urgent issues affecting production agents, enterprise customers have access to priority support with guaranteed response times.

---

ABL Language

What is the difference between ABL and YAML?

ABL is a purpose-built domain-specific language for defining agent behavior. While you can also define agents using YAML in the visual editor, ABL provides richer syntax for flow control (GOTO, GATHER, conditional transitions), a dedicated parser with descriptive error messages, IDE support (VS Code extension with syntax highlighting and diagnostics), and more concise declarations for complex multi-agent setups. YAML mode is available in the Studio visual editor and is convenient for simple agents. For advanced orchestration, ABL is recommended.

My agent has a syntax error but I cannot find it

Check for these common causes:

1. Indentation errors. ABL is indentation-sensitive. Use consistent indentation (2 or 4 spaces, no tabs).
2. Missing keywords. Every block requires its opening keyword (e.g., AGENT CustomerSupport, not just CustomerSupport).
3. Unclosed strings. Multi-line strings must use the pipe (|) or triple-quote syntax.
4. Use the Studio code editor, which shows real-time parser diagnostics with line-specific error messages.

When should I add a FLOW section to my agent?

Choose based on the conversation pattern:

Approach	Use When	Example
No FLOW (default)	The agent needs to decide its own path based on context	Open-ended Q&A, research assistant
With FLOW	The conversation follows a predictable flow with defined steps	Order placement, form filling, onboarding
FLOW + REASONING: true	Some steps are deterministic, others need LLM flexibility	Structured intake flow with reasoning-enabled steps for handling complex issues

How do expressions work in ABL?

Expressions are used in conditions, variable interpolation, and computed values.

Variable interpolation uses double curly braces in strings: "Hello, {{user_name}}!".

Conditional transitions use IF clauses on GOTO statements:

GOTO premium_support IF user.tier == "premium"
GOTO standard_support IF user.tier == "standard"
GOTO fallback

Common expression operators: == (equal), != (not equal), >, <, >=, <= (comparison), AND, OR, NOT (logical).

Can I use ABL with the visual editor?

Yes. The Studio visual editor works with both modes: Code mode for writing ABL directly with syntax highlighting and diagnostics, and Visual mode for using the drag-and-drop flow editor. Changes in one mode are reflected in the other, and you can switch between them at any time.

What happens when ABL parsing fails at runtime?

If the agent was working in Studio but fails when deployed, verify the agent compiles cleanly in Studio before deploying. Check for template variables that resolve at deploy time — if a variable reference is invalid, parsing succeeds but execution fails. Common runtime parse errors include UNKNOWN_STEP (a GOTO references a step that does not exist), DUPLICATE_STEP (two steps have the same name), and INVALID_EXPRESSION (a condition has a syntax error).

How do I define a multi-line instruction?

Use the pipe character for block scalars or triple-quoted strings:

AGENT Support
  INSTRUCTIONS """
    You are a customer support agent for Acme Corp.

    Guidelines:
    - Always verify the customer's identity before making account changes.
    - Escalate billing disputes over $500 to a supervisor.
    - Be empathetic but efficient.
  """

Single-line strings use regular quotes: DESCRIPTION "Handles customer support inquiries".

How do I add comments to ABL?

Use # for line comments:

# This agent handles onboarding
AGENT Onboarding
  DESCRIPTION "Guides new users through setup"

  FLOW
    # First step: collect the user's name
    STEP welcome
      SAY "Welcome! What is your name?"
      GATHER user_name
      GOTO setup

ABL does not support block comments. Use multiple # lines instead.

---

Agent Development

My agent is not using tools correctly

1. Verify tools are bound to the agent. Tools must be declared in the agent definition with TOOLS [order_lookup, ticket_create, knowledge_search].
2. Check tool descriptions. The LLM uses tool descriptions to decide when and how to call them. Vague descriptions like “Looks up stuff” lead to poor tool selection. Write specific, actionable descriptions.
3. Check tool parameters. Ensure parameter names, types, and descriptions are clear so the LLM knows what to pass.
4. Check the trace. Open the session trace to see tool selection decisions. If the agent calls the wrong tool, refine its instructions or tool descriptions.

GATHER is not collecting user input

1. Verify the GATHER syntax. GATHER needs a variable name to store the collected value.
2. Check for missing SAY before GATHER. The agent must prompt the user before gathering input.
3. Validate the collected value. Use constraints to ensure the input meets requirements (e.g., CONSTRAINT email "Please provide a valid email address").
4. Check field types. Ensure the field type matches what you expect the user to provide.
5. Look at the trace to see if the agent asked the user for input. If the GATHER step was skipped, check the transition conditions leading into it.

Flow transitions are not working as expected

1. Check conditional order. Conditions are evaluated top to bottom. The first matching condition wins, so check specific conditions first.
2. Check for missing default transitions. If no condition matches and there is no unconditional GOTO, the flow stalls. Always provide a default.
3. Check step names. GOTO targets must match step names exactly (case-sensitive).
4. Avoid circular references without exit conditions. If steps form a loop, ensure at least one path breaks out.

How does agent memory work?

The Agent Platform 2.0 provides multiple memory scopes:

Scope	Lifetime	Use Case
Session	Current conversation	Turn-by-turn context, gathered values
User	Across sessions for the same user	Preferences, past interactions
Project	Shared across all sessions in a project	Lookup data, shared configuration

Reference session variables directly in ABL with {{user_name}}. Memory size is bounded by the session configuration, and large payloads should be stored as attachments.

How do I use constraints for input validation?

Constraints validate user input during GATHER steps. If validation fails, the agent re-prompts with the error message. Built-in types include email, phone, number, range(min, max), and one_of("option1", "option2"). For complex validation, use llm_validate with a natural-language description of the expected input format.

How do I handle errors in my agent?

Use error handling at the flow level with ON_ERROR GOTO error_handler on tool calls. For tool-level errors, the agent receives the error in its context and can decide how to proceed. Agents without a FLOW section handle errors automatically through LLM reasoning. Agents with a FLOW section need explicit ON_ERROR transitions to define error recovery paths.

How do I pass context between agents in a multi-agent setup?

When a supervisor delegates to a sub-agent, context is passed through the handoff. The delegated agent receives the current message, the conversation history (configurable depth), and any session variables set by the supervisor. Configure routing instructions to specify what context should be included for each specialist agent.

My agent’s responses are too long or too short

Add specific instructions about response style in the agent’s INSTRUCTIONS block (e.g., “Keep responses under 3 paragraphs unless the user asks for detail”). For more control, use MAX_RESPONSE_TOKENS and TEMPERATURE settings in the agent configuration.

My agent gives wrong or unexpected answers

1. Review your instructions. Vague instructions produce vague answers. Be specific about what the agent should and should not do.
2. Check the model. More capable models (e.g., Claude Sonnet, GPT-4o) follow complex instructions better than smaller models.
3. Add guardrails. Use GUARDRAILS to define boundaries for the agent’s behavior.
4. Use the trace. The trace shows the full prompt sent to the LLM, including system instructions, conversation history, and tool results. Review it to understand why the model made a particular decision.

My agent’s tools are not working

1. Verify the tool definition in your agent has no compilation errors (check the Problems panel in the editor).
2. Open the session trace and expand the tool call span. The trace shows the input the agent sent to the tool and the output (or error) returned.
3. For HTTP tools, confirm the target URL is reachable and returns the expected response format.
4. For custom code tools, check that the code does not throw an unhandled exception — the trace will show the stack trace.

How do I debug agent behavior?

1. Start with the trace. It shows exactly what happened, in what order, and what data flowed between steps.
2. Check the LLM prompt. Expand an LLM span to see the full prompt. If the instructions are unclear, the model’s response will be too.
3. Check tool outputs. If a tool returned unexpected data, the agent’s next decision will be based on that bad data.
4. Use multiple test sessions. Try different user inputs to see how the agent handles edge cases. The Test panel preserves session history so you can compare runs.

---

Tools & Integrations

My HTTP tool returns a connection error

If the tool call fails with ECONNREFUSED, ENOTFOUND, or ETIMEDOUT:

1. Verify the endpoint URL. Check for typos, missing protocol (https://), and correct port.
2. Check allowed domains. If allowedServiceDomains is configured in your workspace security settings, the target domain must be in the list.
3. Check timeout. The default service timeout is 30 seconds. For slow APIs, increase the tool-level timeout in the tool definition.

My tool returns a 401 Unauthorized error

1. Check authentication configuration. Verify the API key or token is set correctly in the tool definition or project secrets.
2. For OAuth 2.0: Verify the OAuth connection is configured and the token has not expired. Go to Project > Settings > Tool Secrets to check credential status.
3. Check the API key scope. Some APIs require specific scopes or permissions for each endpoint.

OAuth token refresh fails

1. Verify the refresh token is present. If the OAuth provider did not issue a refresh token during the initial authorization, re-authorize with the offline_access scope.
2. Check the OAuth redirect URI. The configured redirect URI must exactly match what is registered with the OAuth provider (including trailing slashes).
3. Check token expiration. Go to Project > Settings > Integrations and check the OAuth connection status. If it shows “Expired,” re-authorize.
4. Verify the OAuth provider configuration: Client ID, client secret, token endpoint URL, and required scopes must all be correct.

Code tool execution times out

If a Python or JavaScript code tool fails with TIMEOUT or EXECUTION_TIMEOUT:

1. Check the timeout setting. The default sandbox timeout is 60 seconds. For compute-intensive tasks, increase it in the tool definition.
2. Optimize the code. Common causes of slow execution include large data processing without streaming, synchronous HTTP calls inside the sandbox, and unbounded loops.
3. Check sandbox resource limits. The sandbox has memory and CPU constraints. Very large datasets may need to be processed outside the sandbox.

MCP server connection fails

If connecting to an MCP (Model Context Protocol) server fails with “Connection refused” or “Timeout”:

1. Verify the MCP server URL. The URL must be reachable from the runtime.
2. Check the transport type. MCP supports HTTP/SSE and Stdio transports.
3. Check authentication. If the MCP server requires authentication, configure the credentials in the tool connection settings.
4. Check for CORS issues if connecting from the browser. MCP servers must allow the platform’s origin.
5. Verify tool discovery. After connecting, the platform queries the MCP server for available tools. If tools are not appearing, check the MCP server logs for errors.

Tool call returns unexpected results

1. Check the tool response format. The agent receives the tool’s response as structured data. If the response shape changed, the agent may misinterpret it.
2. Add response processing instructions in the tool description so the agent knows how to interpret the returned fields.
3. Check the trace. Open the session trace and expand the tool call to see the raw request and response.
4. Test the tool independently. Use Project > Tools > Test to call the tool with specific parameters and inspect the response.

How do I store tool secrets securely?

Tool secrets (API keys, tokens, credentials) are stored encrypted and referenced by name in tool definitions:

1. Go to Project > Settings > Tool Secrets.
2. Click Add secret and enter a name (e.g., WEATHER_API_KEY) and the secret value.
3. Reference the secret in your tool with {{secrets.WEATHER_API_KEY}}.

Secrets are encrypted at rest and never exposed in traces or logs.

How do I limit which domains tools can call?

Configure the allowed service domains in your workspace security settings at Settings > Security > Allowed service domains. Add the domains your tools need to access. When this list is non-empty, tool HTTP calls to any domain not in the list are blocked. An empty list allows all domains.

My tool works in testing but fails during agent execution

1. Check session context. During agent execution, tool parameters may be populated from session variables. If a variable is missing or has an unexpected value, the tool call fails.
2. Check parameter types. The agent may pass a string where the API expects a number. Ensure proper types in the tool definition.
3. Check concurrent call limits. If your agent calls many tools simultaneously, you may hit the maxConcurrentServiceCalls limit (default: 10).

---

Multi-Agent

Context is lost during agent handoff

1. Check routing instructions. The supervisor’s routing instructions control what context is passed during handoff. Be explicit about what to include for each specialist.
2. Check conversation history depth. By default, the sub-agent receives recent conversation history. If the conversation is long, important early context may be outside the window.
3. Use session variables for critical context that must persist across handoffs.
4. Check the trace. Open the session trace and inspect the handoff event to see exactly what context was passed to the sub-agent.

Delegation times out

1. Check the sub-agent’s configuration. If the sub-agent uses tools that take a long time, the delegation may exceed the timeout. Ensure maxServiceTimeoutMs is sufficient.
2. Check for infinite loops. If the sub-agent’s flow loops without reaching a terminal state, it never returns a response.
3. Check LLM availability. If the sub-agent uses a different model tier than the supervisor, that model may be unavailable or rate-limited.
4. Check the trace. The trace shows the delegation start time, sub-agent execution, and where the timeout occurred.

The supervisor routes to the wrong agent

1. Improve agent descriptions. The supervisor uses agent descriptions to decide routing. Avoid overlapping descriptions; make each agent’s domain distinct.
2. Refine routing instructions. Add explicit routing rules with keyword-to-agent mappings and examples.
3. Use a faster model for routing. The coordination operation type can use the Fast tier for quicker, more focused routing decisions at Project > Settings > LLM Configuration.

How do I implement fan-out (parallel agent execution)?

Fan-out sends the same request to multiple agents in parallel and aggregates their responses. Configure the supervisor with ORCHESTRATION fan_out and list the agents to invoke. The supervisor waits for all agents to respond, then combines the results. Note that all agents must respond within the delegation timeout, fan-out multiplies LLM usage, and if one agent fails, the supervisor receives partial results.

How do I implement agent chaining (sequential delegation)?

Chain agents by having the supervisor route sequentially through routing instructions that specify the order. Each agent in the chain receives the output of the previous agent as part of its context.

How do I handle escalation to a human?

Use the ESCALATE action to transfer the conversation to a human agent. Provide a REASON, optional QUEUE name, and CONTEXT with relevant session data. The escalation pauses the automated agent, sends conversation context to the configured escalation channel (Genesys, Zendesk, or your contact center), and optionally keeps the session open for post-transfer agent assistance.

Can sub-agents use different models?

Yes. Each agent can have its own model configuration set in the agent definition or agent settings. Different operations (tool selection, response generation) can use different tiers. The model resolution chain applies independently to each agent in the multi-agent setup.

My supervisor sometimes responds directly instead of delegating

1. Add explicit delegation instructions telling the supervisor to NEVER answer user questions directly and to always delegate to the appropriate specialist.
2. Reduce the supervisor’s context. If the supervisor has too much knowledge, the LLM may decide it can answer directly. Keep the supervisor’s instructions focused on routing.
3. Use the coordination tier. Set the coordination operation to use a Fast model, which tends to follow routing instructions more strictly.

---

Publishing & Deployment

How do I publish an agent?

1. Open your project in Studio and navigate to the agent you want to publish.
2. Click the Publish button in the top-right corner of the editor.
3. Select the target environment (Development, Staging, or Production).
4. Review the summary of changes since the last publish.
5. Click Confirm to publish.

The agent becomes live on all channels connected to that environment within a few seconds.

How do I roll back to a previous agent version?

Go to Project Settings > Versions, find the version you want to restore, click the three-dot menu, and select Publish this version. Choose the target environment and confirm. Rollbacks take effect within seconds. Active conversations in progress complete using the version they started with; new conversations use the rolled-back version.

What channels are available?

Agent Platform 2.0 supports the following channels out of the box:

Channel	Setup Location	Notes
Web Widget	Project Settings > Channels > Web	Embed a chat widget on any website
REST API	Project Settings > Channels > API	Programmatic access for custom integrations
Slack	Project Settings > Channels > Slack	Requires Slack app installation in your workspace
WhatsApp	Project Settings > Channels > WhatsApp	Requires a WhatsApp Business account
Microsoft Teams	Project Settings > Channels > Teams	Requires Azure Bot registration
SMS	Project Settings > Channels > SMS	Requires a Twilio or compatible provider account

Each channel can be bound to a specific environment so you can test integrations without affecting live users.

How do I add the Web Widget to my website?

Go to Project Settings > Channels > Web, click Create Web Channel, configure appearance options, and copy the embed snippet. Paste the snippet into your website’s HTML just before the closing </body> tag. The widget appears immediately. You can customize the widget’s theme, position, launcher icon, and behavior from the channel settings page — changes apply without updating the embed code.

How do I connect Slack?

Go to Project Settings > Channels > Slack, click Connect Slack, follow the OAuth flow to install the ABL bot into your Slack workspace, select which channels the agent should listen in, choose the target environment, and save. You can configure whether the agent responds to all messages or only when mentioned with @.

How do I connect WhatsApp?

Go to Project Settings > Channels > WhatsApp, enter your WhatsApp Business API credentials, configure the webhook URL in your WhatsApp Business account, select the target environment, and save. You need an approved WhatsApp Business account through Meta.

How do I use the REST API channel?

Go to Project Settings > Channels > API, click Create API Channel, and copy the generated API Key. Use the key to authenticate requests to https://api.ablplatform.com/v1/conversations. Full API reference documentation is available at Project Settings > Channels > API > View API Docs.

What are the different environments?

Agent Platform 2.0 provides three environments for each project:

Environment	Purpose
Development	Build and test your agent. Only accessible to project members through Studio’s built-in test chat.
Staging	Pre-production validation. Connect test channels here to verify behavior before going live.
Production	Live traffic. End users interact with agents through channels connected to this environment.

Each environment maintains its own published agent version, channel connections, and conversation history.

How do I promote an agent between environments?

Publish and test your agent in Development, then go to Project Settings > Versions, find the version, click the three-dot menu, and select Promote to Staging. After testing in Staging, repeat and select Promote to Production. You can also skip Staging and promote directly to Production.

How do agent versions work?

Every time you publish an agent, Agent Platform 2.0 creates an immutable version snapshot that includes the agent definition, knowledge base contents, and connected tool configurations. Drafts are the working copy in the editor (edits do not affect live environments). Published versions are immutable snapshots deployed to a specific environment. Versions are auto-numbered sequentially and retained indefinitely.

How do I check if my agent is healthy?

The Project Dashboard shows a status indicator (green/yellow/red), active conversations, messages processed, and average response time. For detailed metrics, go to Project Settings > Monitoring for error rate, latency percentiles (p50/p95/p99), tool execution success rates, and LLM token usage.

Where do I see error rates and logs?

Go to Project Settings > Monitoring > Errors to see a timeline of errors grouped by type. You can filter by environment, date range, and error type. Click any error to see the full conversation trace including the agent’s reasoning steps and tool calls leading up to the failure.

How do I set up alerts?

Go to Project Settings > Monitoring > Alerts, click Create Alert, and configure the metric (error rate, latency, or conversation volume), threshold, evaluation window, and notification channel (email, Slack webhook, or PagerDuty). Alerts evaluate continuously and can be muted temporarily during planned maintenance.

Does Agent Platform 2.0 auto-scale?

Yes. As a SaaS platform, Agent Platform 2.0 handles scaling automatically. Conversation handling, LLM requests, and knowledge base indexing all scale based on demand. You do not need to provision servers, configure load balancers, or manage infrastructure.

What are the rate limits?

Rate limits depend on your plan:

Resource	Starter	Professional	Enterprise
Messages per minute	60	300	Custom
Concurrent conversations	50	500	Custom
API requests per minute	100	1,000	Custom
Knowledge base documents	500	5,000	Unlimited
Published agents per project	5	25	Unlimited

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in API responses.

How do I increase my rate limits or quotas?

Go to Workspace Settings > Billing & Usage to view your current plan and usage. To upgrade, click Change Plan and select a higher tier. For Enterprise custom limits, click Contact Sales or email [e-mail]. Quota increases on Enterprise plans typically take effect within one business day.

What about self-hosted deployment?

Agent Platform 2.0 offers an enterprise self-hosted option for organizations that require deploying the platform within their own infrastructure. This is available on Enterprise plans and includes dedicated support for installation, configuration, and ongoing operations.

---

Security

How do I add guardrails to my agent?

Guardrails protect against harmful, off-topic, or non-compliant agent behavior. The platform supports input guardrails (check user messages before the agent processes them) and output guardrails (check agent responses before delivery). Configure input guardrails with BLOCK_TOPICS, DETECT_PII, and MAX_INPUT_LENGTH. Configure output guardrails with BLOCK_PATTERNS, REQUIRE_CITATION, and TONE_CHECK.

For workspace-wide guardrails, configure policies at Settings > Security > Guardrail Policies with enforcement modes: Block (reject), Warn (log only), or Redact (remove violating content and continue).

How does PII detection and redaction work?

The platform includes built-in PII detection for email addresses, phone numbers, Social Security numbers, credit card numbers, IP addresses, and custom patterns. In traces, PII is replaced with [REDACTED:type]. In analytics, PII is stripped before storage. In conversations, PII flows through the agent normally — detection is for logging and storage, not blocking. Use input guardrails to block messages containing specific PII types. Add custom PII patterns at Settings > Security > PII Patterns.

How do I rotate API keys?

For workspace API keys: go to Settings > API Keys, create a new key, update your applications, deactivate the old key after a transition period, then delete it. For LLM provider credentials: go to Settings > AI Configuration > LLM Providers, add a new credential, update models to use it, then deactivate the old one. The apiKeyMaxAgeDays setting (default: 90 days) enforces maximum key age with administrator alerts.

How does tenant isolation work?

The Agent Platform 2.0 enforces strict multi-tenant isolation at every layer:

• Data isolation: Every database query includes tenantId. Cross-tenant access returns 404 (not 403) to prevent existence leaking. Encryption keys are per-workspace.
• Runtime isolation: Sessions are scoped to tenantId. Redis keys include the tenant prefix. BullMQ jobs include tenantId and are validated before processing.
• API isolation: JWT tokens include tenantId baked in from authentication. The runtime reads the tenant from the JWT, not from request headers. API keys are scoped to a workspace.

How do I restrict outbound network access?

Go to Settings > Security and configure Allowed service domains with the domains your tools need to access. When this list is non-empty, any HTTP tool call to a domain not in the list is blocked. You can use wildcard patterns (e.g., *.internal.example.com).

How do I audit who did what?

The platform records audit logs for user login/logout, API key management, credential changes, agent deployments, configuration changes, and channel connection changes. Access audit logs at Settings > Security > Audit Logs or via the API. Business and Enterprise plans support exporting audit logs to external SIEM systems. Retention is configurable via auditLogRetentionDays (default: 90 days).

How do I enable SSO?

SSO is available on Business and Enterprise plans and supports SAML 2.0 (Okta, Azure AD, OneLogin, PingOne) and OIDC (Google Workspace, Azure AD, Auth0). Go to Settings > Security > Authentication, click Configure SSO, select the protocol, enter the provider configuration, configure attribute mapping, and test the connection before enabling.

How do I enable MFA?

Go to Settings > Security > Authentication and enable Multi-factor authentication. Choose enforcement: Optional (members can enable in their profile) or Required (all members must enable at next login). Supported methods: TOTP (authenticator app) and WebAuthn (hardware key).

My agent leaks internal information

1. Add output guardrails to block patterns that match internal information.
2. Restrict tool output. If tools return raw internal data, add post-processing to strip sensitive fields before the agent sees them.
3. Refine agent instructions to explicitly prohibit revealing internal system details, API endpoints, database names, or internal error messages.
4. Enable PII redaction to prevent sensitive data from appearing in traces and analytics.

---

Workspace Administration

What roles are available?

Role	Description	Key Permissions
Owner	Full workspace control	All permissions, manage billing, delete workspace
Admin	Workspace administration	Manage members, configure models, manage channels
Operator	Production operations	Monitor sessions, analytics, and deployments
Member	Agent development	Create/edit agents, run tests, manage resources
Viewer	Read-only access	View agents, sessions, analytics

Assign roles at Settings > Team > Members. Projects also have fine-grained permissions including agent:read, workflow:*, channel:create, analytics:read, and deployment:read.

How do I invite team members?

Go to Settings > Team > Members, click Invite member, enter the email address, select a role, and send the invitation. Invitations expire after 7 days. Project access is added separately from Settings > Members using existing workspace members.

How do I set up model configuration?

Quick setup: add credentials at Settings > AI Configuration > LLM Providers, register models at Settings > AI Configuration > Models, assign each model to a tier (Fast, Balanced, Powerful, Voice), and set defaults.

How do I control which providers my team can use?

Use tenant LLM policies at Settings > AI Configuration > Policies. Configure a provider allowlist, model allowlist, and token budgets per project or per user. Policies apply to all projects in the workspace and cannot be overridden at the project level.

How does billing work?

Plan	Billing Model
Free	No charge, usage limits apply
Team	Per-seat monthly subscription
Business	Per-seat + usage-based (tokens, messages)
Enterprise	Custom pricing, annual contract

View usage at Settings > Usage. Upgrade at Settings > Billing > Upgrade plan.

How do I manage environment variables for my project?

Go to Project > Settings > Environment Variables, add variables with scope (all environments or specific environment), and reference them in ABL with {{env.VARIABLE_NAME}}. For sensitive values (API keys, tokens), use Tool Secrets instead — they are encrypted at rest.

How do I manage deployments?

Create deployments at Project > Deployments with a description and target environment. Promote tested deployments to higher environments. Roll back by selecting a previous deployment and clicking Rollback to this version.

How do I export data from my workspace?

• Agent definitions: Export ABL files from Project > Agents > Export.
• Conversations and sessions: Export from Project > Sessions > Export or via the API.
• Analytics: Export from Project > Analytics > Export (Business and Enterprise plans).
• Full workspace export: Available on Enterprise plans — contact your account team.

How do I delete a project?

Click the three-dot menu on the project card, select Delete project, type the project name to confirm, and click Delete permanently. This action is permanent and removes all agents, sessions, channel connections, and analytics data.

How do I transfer workspace ownership?

Go to Settings > Team > Members, find the new owner, change their role to Owner, and confirm. The previous owner is downgraded to Admin. A workspace must always have exactly one owner.

---

Troubleshooting

How do I read an execution trace?

Every agent execution generates a trace — a structured record of what happened, in what order, and how long each step took. Access traces in Studio at Project > Sessions or via the API. A trace contains a tree of spans:

Span Type	Description
session.message	Top-level span for a user message
agent.execute	Agent execution (with or without flow)
llm.call	LLM API call with model, tokens, latency
tool.call	Tool invocation with parameters and result
channel.send	Outbound message delivery
guardrail.check	Guardrail evaluation
handoff	Agent-to-agent delegation

What should I look for in a trace?

Problem	Where to Check
Slow response	Look at llm.call durations and tool.call durations
Wrong tool selected	Expand llm.call to see the tool selection reasoning
Tool error	Expand tool.call to see the error message and response
Wrong agent routing	Check handoff spans for routing decisions
Guardrail block	Check guardrail.check spans for blocked content
Missing response	Look for errors in agent.execute or channel.send

How do I debug tool calls?

Each tool call in the trace includes input parameters, the raw HTTP request and response (for HTTP tools), duration, and any errors. Common tool errors:

• TOOL_TIMEOUT — Increase the tool timeout or optimize the external API.
• ECONNREFUSED — Verify the endpoint URL and network connectivity. Check allowedServiceDomains.
• HTTP 401 — Check the API key or OAuth token. Verify the credential is active in Tool Secrets.
• INVALID_TOOL_RESPONSE — The API may be returning an error page. Check the URL and verify the API is operational.

Test tools independently at Project > Tools > Test to isolate issues from the LLM.

How do I resolve LLM errors?

• MODEL_NOT_FOUND — Register a model for the requested tier at Settings > AI Configuration > Models.
• CREDENTIAL_INVALID — Go to LLM Providers, click Validate, and replace the key if expired.
• RATE_LIMITED (429) — Check your provider’s rate limits, configure fallback models, or reduce the model tier for high-volume operations.
• CONTEXT_OVERFLOW — Use a model with a larger context window, reduce conversation history depth, or summarize older messages.
• LLM_TIMEOUT — Increase llm.timeoutMs, use a faster model, or check the provider’s status page.

How do I inspect session state?

Go to Project > Sessions and click a session to see messages (full conversation history), variables (current session variable values), trace (execution timeline), and metadata (agent, deployment, channel, and timing information).

What do the session states mean?

State	Description
active	Session is open and processing messages
idle	Session is waiting for user input
expired	Session exceeded sessionIdleSeconds or sessionMaxAgeSeconds
ended	Session was explicitly ended by the agent or user
error	Session encountered an unrecoverable error

Why does my session show “not found”?

The SESSION_NOT_FOUND error has three common causes: the session expired and was cleaned up (check sessionIdleSeconds), the JWT tenant does not match the session’s tenant, or the session was created in a different deployment environment.

My session state is stuck

If the session shows as “active” but does not respond to messages, check the trace for a hanging tool.call or llm.call. The session cleanup job will eventually timeout and close it. For immediate resolution, end the session from the Project > Sessions page.

What are the common error codes?

Agent execution errors:

Code	Resolution
AGENT_NOT_FOUND	Verify the agent exists and is deployed
COMPILE_ERROR	Fix syntax errors in the agent definition
EXECUTION_ERROR	Check the trace for the specific error
MODEL_NOT_FOUND	Register a model for the tier
CREDENTIAL_INVALID	Replace or revalidate the credential
CONTEXT_OVERFLOW	Use a larger model or reduce history

Tool errors:

Code	Resolution
TOOL_TIMEOUT	Increase timeout or optimize the tool
TOOL_ERROR	Check the tool’s response in the trace
TOOL_NOT_FOUND	Verify the tool is defined and bound to the agent
SANDBOX_TIMEOUT	Optimize code or increase sandbox timeout
DOMAIN_BLOCKED	Add the domain to allowedServiceDomains

Channel errors:

Code	Resolution
CHANNEL_NOT_CONFIGURED	Create a channel connection for the channel type
SIGNATURE_INVALID	Check channel credentials (signing secret, auth token)
DELIVERY_FAILED	Check channel API status and credentials

Session errors:

Code	Resolution
SESSION_NOT_FOUND	Create a new session or check timeouts
SESSION_LIMIT	Upgrade plan or close idle sessions
RATE_LIMIT_EXCEEDED	Wait for the rate limit window to reset

Authentication errors:

Code	Resolution
UNAUTHORIZED	Provide a valid JWT or API key
FORBIDDEN	Check role and permission assignments
TOKEN_EXPIRED	Refresh the token

How do I check the platform health?

Visit status.ablplatform.com for real-time service status, uptime metrics, active incident details, and scheduled maintenance windows. Subscribe to status updates via email, RSS, or webhook.

How do I increase log verbosity for debugging?

Set observability.loggingLevel to debug, reproduce the issue, search logs for the session ID or error code, and then return the log level to info. In production, use trace sampling (observability.traceSamplingRate, default 1.0) to control how many traces are stored — set to 0.1 or 0.01 for high-traffic environments and use error-based sampling to capture all error traces.