Configure and run BYOA agents

What this does

BYOA means Bring Your Own Agent. A BYOA agent is a customer-operated AI or automation agent that LoopIQ can register, govern, assign work to, invoke, and audit. Use BYOA when you want an external agent, worker, MCP runtime, CLI agent, webhook service, or coding agent to work on LoopIQ records while still respecting organization, team, permission, approval, and audit boundaries.

How BYOA agents are different from ITSM agent identities

LoopIQ has more than one concept with the word agent. They are not interchangeable.

Concept	What it represents	Typical use
BYOA agent	An organization-scoped external AI or automation agent configured by a customer	Implement work, analyze records, draft outputs, create governed comments or evidence, run as a task assignee
ITSM agent identity	An infrastructure or service identity used for operational identity and routing	Represent a service, integration, or operational identity in ITSM-related contexts
Human user	A person with a LoopIQ account, roles, and permissions	Own work, approve actions, update records, review agent output

A BYOA agent can be assigned to supported work items like a human assignee, but it is not a human user account. Its actions are governed through BYOA permissions, allowed surfaces, mutation policies, approval policies, task events, invocations, and output attachments.

What BYOA agents can do today

BYOA agents can:

be created and managed inside an organization
be scoped to a team when an agent should only operate for one team
be filtered by active status, provider type, team, and allowed surface
appear in supported assignee flows for stories, tasks, and issues
automatically receive a BYOA task when assigned to a supported work item
claim queued tasks through a runtime worker
report progress, blockers, output, completion, failure, or cancellation
be invoked directly when configured as a webhook agent
be invoked by automation rules and approval hooks
return governed outputs such as audit records, comments, evidence, or status-change requests
require human approval before sensitive actions are applied
keep an auditable history of invocations, task events, approvals, and output attachments

Direct live invocation currently requires provider_type set to webhook. Other provider types can still be registered for cataloging and task-queue patterns, but direct synchronous execution is only enabled for webhook agents.

Key concepts

Term	Meaning
Agent definition	The BYOA agent record that stores name, provider type, endpoint, auth mode, capabilities, surfaces, schemas, policies, and active state
Surface	The kind of LoopIQ object the agent works on, such as `story`, `task`, `issue`, `incident`, `release`, or `evidence`
Surface ID	The record identifier for the selected surface. Picker responses include a human-readable `BusinessID - Title` label
Invocation	A run of a BYOA agent against a surface and input payload
Task	A durable work item assigned to a BYOA agent and claimed by a runtime
Runtime	The worker process that claims and executes queued BYOA tasks
Task event	A progress, heartbeat, blocker, output, completion, failure, or cancellation event written by the runtime
Approval event	A human review request created when BYOA output contains actions that need approval
Output attachment	The governed record of BYOA output, comments, evidence, or action results

Before you begin

Make sure:

your organization has BYOA enabled
your role can view, create, edit, or delete BYOA agents
the organization context is correct if you belong to more than one organization
the team context is correct if the agent is team-scoped
the external agent endpoint, runtime, or worker is ready
secrets are available through auth_secret or an external secret_reference
the agent’s allowed surfaces match the records it should work on
mutation and approval policies are reviewed before enabling write actions

Useful permission keys include:

automation.byoa.agents.view
automation.byoa.agents.create
automation.byoa.agents.edit
automation.byoa.agents.delete

Some environments also map BYOA access through related automation-rule permissions. If you see access denied, ask an organization administrator to review both BYOA agent permissions and automation permissions.

Supported providers and auth modes

BYOA agent provider types:

webhook
mcp
openai_compatible
google_vertex
aws_bedrock
azure_openai
other

BYOA auth types:

none
api_key
bearer_token
basic
oauth2
signed_webhook

For api_key, LoopIQ sends the secret in the header named by auth_config.header_name, or X-API-Key if no header name is configured. For bearer_token and oauth2, LoopIQ sends Authorization: Bearer <secret>. For basic, set auth_config.username and provide the password through auth_secret. For signed_webhook, LoopIQ signs the request body with the configured secret and sends signature headers. Do not put secret values in auth_config, metadata, input_schema, or output_schema. Use auth_secret for write-only secret entry or secret_reference when secrets are managed outside LoopIQ.

Supported surfaces

BYOA agents can be configured for these surfaces:

work_item
idea
story
task
issue
product
application
module
feature
enhancement_request
workflow
automation_rule
approval_policy
incident
change_request
service_request
test_execution
release
compliance
exception
deviation
evidence

Surface aliases are normalized in common cases. For example, change maps to change_request, enhancement maps to enhancement_request, and test maps to test_execution. For work item assignment, the supported work item surfaces are story, task, and issue.

Supported capabilities

Capabilities describe what the agent is expected to do. They are used for routing, filtering, and runtime compatibility. Common capabilities include:

analyze
classify
draft
enrich
recommend
route
summarize
validate
implement
test
review
open_pull_request
create_patch
run_command
investigate

Capabilities do not automatically grant permission to mutate LoopIQ records. Mutations are controlled by mutation_policy, approval settings, and the user’s or runtime’s API permissions.

Create a BYOA agent

Use the BYOA agents area in LoopIQ if it is available in your environment. You can also create agents through the API.

Open the BYOA agents page from the AI and Agents area.
Choose New BYOA agent.
Enter a clear name and description.
Select the provider type.
For a live direct invocation, select webhook and enter endpoint_url.
Select the auth type.
Enter non-secret auth metadata in auth_config.
Enter the secret through the secret field, or provide secret_reference.
Select the allowed surfaces.
Select the capabilities.
Set the timeout between 1 and 120 seconds.
Decide whether the agent always requires human approval.
Review the mutation policy and output attachment policy.
Save the agent.
Run a low-risk test before using the agent on production work.

Example API request:

POST /api/{organization}/ai/byoa/agents/
{
  "name": "Implementation Agent",
  "description": "External coding agent for story and task implementation.",
  "provider_type": "webhook",
  "endpoint_url": "https://agent.example.com/loopiq/byoa",
  "auth_type": "signed_webhook",
  "auth_secret": "replace-with-secret",
  "allowed_surfaces": ["story", "task", "issue"],
  "capabilities": ["implement", "test", "review", "create_patch"],
  "default_timeout_seconds": 60,
  "requires_human_approval": true,
  "mutation_policy": {
    "can_apply_output": true,
    "can_create_comment": true,
    "can_attach_evidence": false,
    "can_update_status": false,
    "can_transition_release": false,
    "can_create_work_item": false,
    "requires_approval_for_sensitive_actions": true,
    "sensitive_actions": ["update_status", "create_work_item", "attach_evidence"]
  },
  "output_attachment_policy": {
    "auto_attach_output": true,
    "attach_summary_as_comment": false,
    "include_raw_output": true
  },
  "is_active": true
}

Use the organization identifier in the path segment after /api/. In production this usually looks like:

https://api.loopiq.com/api/{organization}/ai/byoa/agents/

Find a surface to assign or invoke against

Use the surface options endpoint to power searchable pickers. Select the surface type first, then search only within that type.

GET /api/{organization}/ai/byoa/surface-options/?surface_type=story&q=checkout&limit=20

Each option includes:

id
surface_type
business_id
title
label

The label is formatted as BusinessID - Title when both values are available. Use id as the surface_id in assignment and invocation calls. If no options return:

confirm the selected surface_type
check that records exist in the same organization
check team context and permissions
search by business ID or title
reduce filters and try again

Assign a work item to a BYOA agent

Stories, tasks, and issues can be assigned to a BYOA agent.

Open the story, task, or issue.
Choose the assignee field.
Select BYOA Agent if the UI separates human and agent assignees.
Choose an active BYOA agent that is enabled for that work item surface.
Save the work item.

When the work item is saved, LoopIQ creates or updates an active BYOA task for that work item. If the agent requires human approval, the task and invocation start in needs_review. Otherwise, the task starts in queued. For work-item assignment, requires_human_approval pauses the generated task before a runtime can claim it. If the agent should start work automatically and only pause before sensitive mutations, leave requires_human_approval off and put sensitive output actions in sensitive_actions instead. If you change the work item to a different BYOA agent, active BYOA tasks for the previous agent are cancelled. If you clear the BYOA assignee, active BYOA tasks for that work item are cancelled.

Assign a task manually through the API

Use this when an admin or workflow wants to create a BYOA task directly instead of assigning the agent through a work item assignee field.

POST /api/{organization}/ai/byoa/tasks/
{
  "agent": "00000000-0000-0000-0000-000000000000",
  "title": "Implement checkout retry handling",
  "instructions": "Inspect the linked story, implement the retry behavior, run tests, and report the branch or PR.",
  "surface_type": "story",
  "surface_id": "11111111-1111-1111-1111-111111111111",
  "priority": "high",
  "input_payload": {
    "repository": "loopiq/web",
    "expected_output": "summary, changed files, tests, and pull request link"
  },
  "external_reference": "STORY-123",
  "worktree_ref": "feature/checkout-retry"
}

The created task has a generated task_id such as BYOA-TASK-... and an associated invocation such as BYOA-RUN-....

Runtime worker flow

A runtime is the worker process that does the actual agent work. A runtime can be a local daemon, cloud worker, CLI agent, webhook worker, MCP worker, or another worker type. Runtime types include:

local_daemon
cloud_worker
cli_agent
webhook_worker
mcp_worker
other

1. Claim the next queued task

POST /api/{organization}/ai/byoa/tasks/claim/
{
  "agent": "00000000-0000-0000-0000-000000000000",
  "runtime_id": "codex-worker-prod-1",
  "runtime_name": "Codex Worker Prod 1",
  "runner_type": "cli_agent",
  "supported_surfaces": ["story", "task", "issue"],
  "supported_capabilities": ["implement", "test", "review", "create_patch"],
  "max_concurrent_tasks": 1,
  "start_immediately": true
}

LoopIQ returns the claimed task and the runtime. If start_immediately is true, the task moves to running. Otherwise, it moves to claimed.

2. Send heartbeats and progress events

Use task events for detailed progress notes:

POST /api/{organization}/ai/byoa/tasks/{task_uuid}/events/
{
  "event_type": "progress",
  "message": "Created implementation branch and started tests.",
  "progress_percent": 35,
  "payload": {
    "branch": "feature/checkout-retry"
  }
}

Use runtime heartbeat when the worker needs to report capacity or health:

POST /api/{organization}/ai/byoa/runtimes/{runtime_uuid}/heartbeat/
{
  "status": "busy",
  "current_task_count": 1,
  "metadata": {
    "host": "runner-01",
    "version": "2026.05.12"
  }
}

3. Mark the task blocked if human input is needed

POST /api/{organization}/ai/byoa/tasks/{task_uuid}/status/
{
  "status": "blocked",
  "message": "Repository access is missing for loopiq/web.",
  "progress_percent": 40,
  "payload": {
    "missing_access": "github_repository"
  }
}

A blocked task moves its invocation to needs_review.

4. Complete the task

POST /api/{organization}/ai/byoa/tasks/{task_uuid}/status/
{
  "status": "completed",
  "message": "Implementation completed and tests passed.",
  "result_payload": {
    "summary": "Added retry handling and test coverage for checkout timeout failures.",
    "branch": "feature/checkout-retry",
    "pull_request_url": "https://github.com/example/repo/pull/123",
    "actions": [
      {
        "type": "create_comment",
        "title": "BYOA implementation summary",
        "content": "Implementation completed. See pull request for changed files and tests."
      }
    ]
  }
}

When a task completes, LoopIQ governs the output. Allowed actions are applied immediately or sent for approval depending on the agent policy. Denied actions are recorded as blocked action results.

Direct webhook invocation flow

Use direct invocation when LoopIQ should call a webhook agent immediately and wait for a response.

POST /api/{organization}/ai/byoa/agents/{agent_uuid}/invoke/
{
  "surface_type": "story",
  "surface_id": "11111111-1111-1111-1111-111111111111",
  "trigger_type": "manual",
  "correlation_id": "STORY-123",
  "input": {
    "prompt": "Review this story and recommend implementation steps."
  },
  "context": {
    "source": "story_detail"
  }
}

LoopIQ sends a webhook body with:

agent
organization
surface
trigger
input
context

LoopIQ also sends headers such as:

X-LoopIQ-Agent-Id
X-LoopIQ-Invocation-Id
X-LoopIQ-Organization-Id
X-LoopIQ-Surface-Type

The webhook response should be JSON when possible. If the response contains actions or attachments, LoopIQ evaluates them through the mutation and approval policy. If no actions are provided and auto_attach_output is enabled, LoopIQ stores the output as an audit record or comment depending on the output attachment policy.

Output actions and governance

Supported governed action types include:

attach_output
create_comment
attach_evidence
policy_evidence
attach_release_dossier
test_evidence
exception_evidence
update_status
transition_release
create_work_item

Common aliases are accepted. For example, comment maps to create_comment, evidence maps to attach_evidence, and set_status maps to update_status. Each action is checked against mutation_policy.

Policy key	Controls
`can_apply_output`	Whether generic output can be attached as an audit record
`can_create_comment`	Whether the agent can create comments
`can_attach_evidence`	Whether the agent can attach evidence-related records
`can_update_status`	Whether the agent can update a target status
`can_transition_release`	Whether the agent can transition release-related state
`can_create_work_item`	Whether work item creation action requests are permitted by governance
`requires_approval_for_sensitive_actions`	Whether sensitive allowed actions still require approval
`sensitive_actions`	The action types that should route to approval

For high-impact workflows, keep requires_human_approval enabled or keep sensitive actions in sensitive_actions.

Review and approve BYOA actions

When BYOA output needs review, the invocation status becomes needs_review and LoopIQ creates a pending approval event. To approve:

POST /api/{organization}/ai/byoa/invocations/{invocation_uuid}/decision/
{
  "decision": "approved",
  "comment": "Approved after code review.",
  "apply_actions": true
}

To reject:

POST /api/{organization}/ai/byoa/invocations/{invocation_uuid}/decision/
{
  "decision": "rejected",
  "comment": "Rejected because the proposed status change is not valid.",
  "apply_actions": false
}

Approved actions can move the invocation to applied. Rejected actions move it to rejected.

Automation and approval hooks

Automation rules can run a BYOA agent with the run_byoa_agent action type. Live automation invocation uses the same direct invocation path as manual invocation, so the agent must be executable by LoopIQ. Today that means a webhook BYOA agent for synchronous execution. Approval policies and workflow hooks can reference BYOA agents through fields such as:

agent_id
agent
byoa_agent_id

When automation invokes a BYOA agent, LoopIQ validates that:

the agent belongs to the same organization
the agent is active
the agent is enabled for the target surface
the agent’s team scope does not conflict with the automation target
requested mutations are allowed by policy

Monitor BYOA work

Use these endpoints to monitor BYOA activity:

Endpoint	Purpose
`GET /api/{organization}/ai/byoa/agents/`	List configured BYOA agents
`GET /api/{organization}/ai/byoa/tasks/`	List assigned BYOA tasks
`GET /api/{organization}/ai/byoa/tasks/{task_uuid}/events/`	Review task progress events
`GET /api/{organization}/ai/byoa/invocations/`	Review invocation history
`GET /api/{organization}/ai/byoa/approvals/`	Review approval events
`GET /api/{organization}/ai/byoa/output-attachments/`	Review governed output attachments
`GET /api/{organization}/ai/byoa/runtimes/`	Review worker runtimes and heartbeat state

Useful task statuses:

assigned
queued
claimed
running
blocked
needs_review
completed
failed
cancelled

Useful invocation statuses:

queued
running
succeeded
failed
cancelled
needs_review
approved
rejected
applied

Troubleshooting

The BYOA agent is not visible in an assignee picker

Check that the agent is active, belongs to the same organization, is allowed for the selected surface, and is not scoped to a different team.

Surface search returns no results

Make sure the UI or client sends surface_type and q. Search is limited to the selected surface type. For work items, use story, task, issue, or work_item.

A task is queued but no agent picks it up

Confirm a runtime is running, authenticated, using the same organization, and claiming with the correct agent or runtime_id. Also check max_concurrent_tasks and current runtime capacity.

A task moved to needs review

The agent may require human approval, the output may include sensitive actions, or a blocker may have been reported. Review the invocation approval events and task events.

A direct invocation fails for a non-webhook agent

Direct synchronous invocation currently supports webhook agents. Use the task queue and a runtime worker for other provider styles.

A mutation was not applied

Check mutation_policy, sensitive_actions, approval status, and whether the target surface can be resolved. Blocked actions are stored as output attachments with action-result details.

Access is denied

Confirm your role has BYOA agent permissions, the request includes valid authentication, and the organization identifier in the path matches your selected organization.

Best practices

Start with read-only or comment-only policies.
Scope agents to a team when possible.
Keep direct status changes, evidence attachment, release transitions, and work item creation requests behind approval.
Use signed_webhook or bearer auth for production webhooks.
Keep external workers idempotent because task status updates can be retried.
Log task_id, invocation_id, and runtime_id in external agent logs.
Return clear summaries and structured actions from agents.
Avoid sending secrets or cross-organization data in prompts and payloads.
Test each agent on non-critical records before allowing production mutations.

Welcome

Getting Started

Navigation and Workspace

Ideas

ITSM

Project Management

Test Management

Compliance

Automation

Administration

Integrations and Data

AI and Agents

Analytics

Time Tracking

Audience Tracks

Troubleshooting

Documentation Index

​Configure and run BYOA agents

​What this does

​How BYOA agents are different from ITSM agent identities

​What BYOA agents can do today

​Key concepts

​Before you begin

​Supported providers and auth modes

​Supported surfaces

​Supported capabilities

​Create a BYOA agent

​Find a surface to assign or invoke against

​Assign a work item to a BYOA agent

​Assign a task manually through the API

​Runtime worker flow

​1. Claim the next queued task

​2. Send heartbeats and progress events

​3. Mark the task blocked if human input is needed

​4. Complete the task

​Direct webhook invocation flow

​Output actions and governance

​Review and approve BYOA actions

​Automation and approval hooks

​Monitor BYOA work

​Troubleshooting

​The BYOA agent is not visible in an assignee picker

​Surface search returns no results

​A task is queued but no agent picks it up

​A task moved to needs review

​A direct invocation fails for a non-webhook agent

​A mutation was not applied

​Access is denied

​Best practices

​Related articles

Configure and run BYOA agents

What this does

How BYOA agents are different from ITSM agent identities

What BYOA agents can do today

Key concepts

Before you begin

Supported providers and auth modes

Supported surfaces

Supported capabilities

Create a BYOA agent

Find a surface to assign or invoke against

Assign a work item to a BYOA agent

Assign a task manually through the API

Runtime worker flow

1. Claim the next queued task

2. Send heartbeats and progress events

3. Mark the task blocked if human input is needed

4. Complete the task

Direct webhook invocation flow

Output actions and governance

Review and approve BYOA actions

Automation and approval hooks

Monitor BYOA work

Troubleshooting

The BYOA agent is not visible in an assignee picker

Surface search returns no results

A task is queued but no agent picks it up

A task moved to needs review

A direct invocation fails for a non-webhook agent

A mutation was not applied

Access is denied

Best practices

Related articles