---
title: "Agents - DreamFactory Documentation"
source: "http://wiki.dreamfactory.com/AI_Services/Agents"
canonical_url: "http://wiki.dreamfactory.com/AI_Services/Agents"
converted_at: "2026-10-22T18:51:05.684Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
[]()
	
	
	
	# AI Services/Agents

	
		From DreamFactory Wiki
		
		
		
		
		[Jump to navigation](#mw-head)
		[Jump to search](#searchInput)
		**Register AI agents in DreamFactory with their own identity, role-scoped API key, and skills, and route tasks to the right agent with a deterministic capability router**

## Contents

- [1 Agents](#Agents)

- [1.1 Registering an agent](#Registering_an_agent)

- [1.2 Approving access requests](#Approving_access_requests)

- [1.3 Routing a task to an agent](#Routing_a_task_to_an_agent)

- [1.3.1 How scoring works](#How_scoring_works)

- [1.4 Next steps](#Next_steps)

# Agents

The **Agents** service gives every AI agent its own identity inside DreamFactory: a named record, a role that scopes what it may reach, its own API key with an optional lifetime, and a list of skills. Because an agent is a first-class record rather than a shared key, you can see which agent did what, revoke one without disturbing the others, and route work to the right agent programmatically.

Create the service from **API Generation & Connections** by adding a service of type **Agents**. It exposes three resources:

Resource

Purpose

`/api/v2/agents/agents`

The agent registry — create, read, update, delete agents

`/api/v2/agents/requests`

The pending access-request queue

`/api/v2/agents/route`

Deterministic capability router (POST only)

---

## Registering an agent

An agent record carries:

Field

Description

`name`

The agent's name. Also scored by the router.

`description`

Free-text description. Also scored by the router.

`role_id`

The role that scopes what this agent may reach.

`owner_id`

The user who owns the agent.

`api_key`

The agent's own API key.

`key_ttl_hours`

Optional lifetime for the key, in hours.

`skills`

JSON array of capability keywords, for example `["invoice reconciliation", "refunds"]`.

`chat_service_id`

Optional AI chat service to use as this agent's persona.

`is_active`

Only active agents are considered by the router.

Scope each agent with a role exactly as you would an application. See [Role-Based Access Control](/Security/Role_Based_Access).

---

## Approving access requests

Requests queue under `/api/v2/agents/requests`. Approving or denying one is a `PATCH` that sets the status — the model applies the side effects, including the resolution stamp, key rotation on approval, and the alert:

```
curl -X PATCH \
  "https://{instance}/api/v2/agents/requests/{id}" \
  -H "X-DreamFactory-API-Key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"status": "approved"}'

```

Use `"denied"` to reject. The admin UI's one-click approve is this same call.

---

## Routing a task to an agent

`POST /api/v2/agents/route` answers "which registered agent should handle this?" without calling a model. The scoring is pure and deterministic: the same task and the same registry always produce the same answer.

```
curl -X POST \
  "https://{instance}/api/v2/agents/route" \
  -H "X-DreamFactory-API-Key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"task": "reconcile last month'\''s invoices", "top": 3}'

```

Field

Description

`task`

**Required.** Free-form description of the work.

`top`

How many scored agents to return. Defaults to `3`, clamped to `1`–`25`.

A match returns the winner, its chat persona service if one is configured, a human-readable reason, and the leaderboard:

```
{
  "routed_to": { "id": 4, "name": "Finance Bot" },
  "chat_service_id": 12,
  "chat_service": "finance_chat",
  "reason": "matched: skill:invoice reconciliation",
  "scores": [
    { "id": 4, "name": "Finance Bot", "score": 4 },
    { "id": 7, "name": "Support Bot", "score": 1 }
  ]
}

```

When nothing scores above zero, `routed_to` and the chat fields are `null` and `reason` is `no registered agent matches` — the caller decides what to do next.

### How scoring works

Only active agents are considered. The task, each skill keyword, and each agent's name plus description are tokenized the same way: lowercased, split on runs of non-alphanumeric characters, tokens shorter than three characters dropped, then de-duplicated. Then:

- **+3** for each skill keyword whose tokens *all* appear in the task, so a multi-word skill like `invoice reconciliation` counts once as a single hit rather than twice as two words

- **+1** for each name or description token found in the task, skipping any token already counted as part of a matched skill, so nothing is double-counted

Results are sorted by score, ties broken by lowest id. The practical consequence: **skills drive routing**, and name and description only break ties. If an agent is being picked for the wrong work, edit its skills first.

**ℹ️ Note: The router returns a decision, never a credential** The response contains an agent id, name, and chat service. It never returns `api_key` or any other credential material — the routing call is safe to expose to a client that is not itself trusted with agent keys. `GET` is not supported on this resource; routing is a computed action, so it is `POST` only.
---

## Next steps

- **[Role-Based Access Control](/Security/Role_Based_Access)**: Scope what an agent may reach

- **[AI Chat](/AI_Services/AI_Chat)**: Configure the chat service an agent uses as its persona

- **[MCP Server](/AI_Services/Mcp_Service)**: Expose your APIs to agents as tools

Retrieved from "[https://wiki.dreamfactory.com/index.php?title=AI_Services/Agents&oldid=951](https://wiki.dreamfactory.com/index.php?title=AI_Services/Agents&oldid=951)"
		[Categories](/Special:Categories): - [Ai Agents](/index.php?title=Category:Ai_Agents&action=edit&redlink=1)
- [Agent Identity](/index.php?title=Category:Agent_Identity&action=edit&redlink=1)
- [Capability Router](/index.php?title=Category:Capability_Router&action=edit&redlink=1)
- [Difficulty Intermediate](/Category:Difficulty_Intermediate)