> ## Documentation Index
> Fetch the complete documentation index at: https://help.loopiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

Example API request:

```http theme={null}
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:

```text theme={null}
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.

```text theme={null}
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.

1. Open the story, task, or issue.
2. Choose the assignee field.
3. Select `BYOA Agent` if the UI separates human and agent assignees.
4. Choose an active BYOA agent that is enabled for that work item surface.
5. 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.

```http theme={null}
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

```http theme={null}
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:

```http theme={null}
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:

```http theme={null}
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

```http theme={null}
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

```http theme={null}
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.

```http theme={null}
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:

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

To reject:

```http theme={null}
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.

## Related Articles

* [Use AI Agents and Agent Settings](/ai-and-agents/use-ai-agents-and-agent-settings)
* [Use LoopIQ MCP Tools](/ai-and-agents/use-loopiq-mcp-tools)
* [Create an Automation Rule](/automation/create-an-automation-rule)
* [Manage Roles, Permissions, and Access](/administration/manage-roles-permissions-and-access)
* [Access Denied Because of Permissions](/troubleshooting/access-denied-because-of-permissions)