> For the complete documentation index, see [llms.txt](https://docs.fastn.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fastn.ai/~/revisions/m0hEPQFsdMhQVmegKM0n/reference/ai-agents-reference.md).

# AI Agents Reference

For detailed descriptions of what each agent does, see the [AI Agents section](https://docs.fastn.ai/~/revisions/aj5eaS57qHvafrgYtfbL/ai-agents). This page covers the technical specifications.

### Platform agents

#### Orchestrated agents

| Orchestrator        | Sub-agents                                                                                                | Entry point                                               |
| ------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **Connector Agent** | Connector Builder, Spec Import Builder, Manual Action Builder, Event Builder, Action Tester, Action Fixer | **"Build with AI"** on Connectors page                    |
| **Workflow Agent**  | Planner Agent, Workflow Builder, Test Case Agent                                                          | **"Build with AI"** on Workflows page (orchestrator mode) |

#### Standalone agents

| Agent                           | Purpose                                                              | Entry point                             |
| ------------------------------- | -------------------------------------------------------------------- | --------------------------------------- |
| **SaaS Onboarding**             | Guide SaaS companies through platform setup                          | **Home** → Setup Assistants             |
| **Tenant Onboarding**           | Guide customers through widget-based integration setup               | Embedded widget                         |
| **Intelligence Brief**          | Research companies, produce integration strategy briefs              | Part of SaaS Onboarding (Research step) |
| **Configuration Agent**         | Probe live APIs, define filter conditions and targets                | During integration building             |
| **Standalone Workflow Builder** | Build + validate workflows only (no planner/config/connector agents) | **"Build with AI"** on Workflows page   |

### AgentTool interface

```typescript
interface AgentTool {
  name: string;
  description: string;
  inputSchema: JSONSchema;
  handler: (input: any, context: AgentContext) => Promise<any>;
}
```

### AgentContext

| Property     | Type             | Description                                                |
| ------------ | ---------------- | ---------------------------------------------------------- |
| `connectors` | ConnectorClients | Authenticated connector clients scoped to current customer |
| `tenant`     | CustomerContext  | Customer info: id, name, config                            |
| `user`       | UserContext      | Current user info: id, email, role                         |
| `memory`     | MemoryManager    | Access to all 4 memory layers                              |
| `session`    | SessionContext   | Session ID, conversation history                           |
| `config`     | object           | Configuration values                                       |
| `logger`     | Logger           | Structured logging                                         |

### Agent Builder lifecycle

| State        | Description                                              |
| ------------ | -------------------------------------------------------- |
| `PLANNING`   | User describes agent goal. Planner designs architecture. |
| `PLANNED`    | Architecture specification ready for review.             |
| `GENERATING` | Generator produces implementation files in memory.       |
| `GENERATED`  | Code ready. Synthesizer merges and validates.            |
| `TESTING`    | Ephemeral agent created for interactive testing.         |
| `DEPLOYED`   | Full AgentConfig registered in the platform.             |
| `FAILED`     | Validation or generation failed.                         |

### 4-layer memory system

| Layer          | Storage             | Purpose                                       | TTL                    |
| -------------- | ------------------- | --------------------------------------------- | ---------------------- |
| **Episodic**   | pgvector (1536-dim) | Conversation history, decisions, outcomes     | Permanent (with decay) |
| **Semantic**   | pgvector (1536-dim) | Facts about entities (SaaS, customers, users) | Permanent              |
| **Procedural** | pgvector (1536-dim) | Learned workflows and success rates           | Permanent              |
| **Working**    | Redis               | Active session context                        | 4 hours                |

#### Memory Manager

* **Context assembly**: Parallel retrieval from all 4 layers, priority-based token budgeting (2000 tokens max)
* **Session promotion**: Facts → semantic memory, outcomes → episodic memory, working memory → cleared
* **Search**: Cosine similarity with access-count reinforcement for episodic, incremental success rate for procedural


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fastn.ai/~/revisions/m0hEPQFsdMhQVmegKM0n/reference/ai-agents-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.