> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/agent/platform-functions.md).

# Platform Functions

{% hint style="info" %}
**API Name**: Platform functions are managed through the Agent Forge CLI, the platform SDK, and the Developer Console's Warehouse tab (Tools > Warehouse), which provides a read-only directory, inspector, and test runner, in addition to the workspace-scoped `functions` endpoints. See the [Developer Guide](https://docs.amigo.ai/developer-guide/platform-api/platform-api/functions) for endpoint details.
{% endhint %}

Platform functions are the universal tool primitive. They are declarative - you write a SQL query, a Python function, or compose AI operations, register the function, and agents can call it during conversations. No container, no deployment pipeline, no custom dependencies. The function runs on the platform's compute layer and returns results directly to the agent.

The key capability is cross-domain querying. Platform functions can read both live entity data (the world model's operational store) and analytical aggregations (historical trends, billing data, population statistics) in a single call. A platform function can answer "what is this patient's confidence score across all data sources and how does their utilization compare to the practice average?" in one query.

```mermaid
flowchart LR
    agent["Agent mid-conversation"] --> fn{Function Type}
    fn --> sql["SQL\n(query live + analytical data)"]
    fn --> ai["AI\n(classify, extract, summarize)"]
    fn --> py["Python\n(custom logic)"]
    fn --> tvf["Table-valued\n(multi-row results)"]
    sql --> result["Structured result\nback to agent"]
    ai --> result
    py --> result
    tvf --> result
```

## Tool Categories

Every platform function registers into the tool system. The agent sees them identically - a tool name, a description, an input schema, and a result. Context graph states control availability through `tool_call_specs`. There is no separate dispatch path. Two families of tools register at session start:

* **Named platform functions** - addressed as `fn_<name>`, these are pre-built queries or computations registered for the workspace. Each runs on the platform's compute layer.
* **Workspace data queries** - addressed as `wsq_<name>`, these are parameterized SQL templates that run directly against a workspace's own custom tables. Parameters are typed with optional defaults, write-time validation rejects multi-statement and session-state SQL, and execution runs under the workspace's tenant-scoped role.

### Named Functions

Named functions are pre-built queries or computations registered for the workspace. Each function has a name, description, input schema, and return type. The agent calls them by name with structured parameters.

Function types:

| Type             | What It Does                                                                                     | Example                                                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| **SQL**          | Parameterized query that returns rows or a single computed value across live and analytical data | Patient summary, caller history, entity confidence assessment, risk score                                                   |
| **AI**           | A query that wraps an AI operation such as classify, summarize, extract, or assess               | Intent classification, clinical extraction, transcript cleanup, care plan generation, handoff summaries, urgency assessment |
| **Python**       | A sandboxed scalar function for custom logic                                                     | Address parsing, custom scoring algorithms, phone formatting                                                                |
| **Table-valued** | A sandboxed function that returns multiple rows                                                  | Expanding a record into per-line-item rows, derived tabular results                                                         |

The platform ships with built-in functions, and a workspace can register additional named functions of any type.

{% hint style="success" %}
**Core Built-In Functions**

Always available in every workspace:

* **Entity confidence** - Per-source trust assessment showing which data sources are reliable and which need verification (SQL)
* **Caller history** - Prior call outcomes, quality scores, and conversation summaries for a phone number (SQL)
* **Patient summary** - Concise patient briefing with demographics, event counts, sources, and recent activity (SQL)
* **Patient memory snapshot** - Full memory state for an entity: all extracted memories across configured dimensions with recency and confidence (SQL)
* **Patient dimension summary** - Aggregated per-dimension summary with weighted scores, useful for quick context without loading full memory (SQL)
  {% endhint %}

Beyond the core built-ins, a workspace registers additional named functions. These span SQL queries, AI operations (intent classification, clinical extraction, sentiment analysis, care plan generation, handoff summaries, urgency assessment, medical translation), Python functions (risk scoring, phone formatting, address parsing), and table-valued functions. The available set depends on what the workspace has registered. Any registered function that carries a description becomes an agent tool, with that description serving as the tool description the agent sees.

### Workspace Data Queries

Workspace data queries (`wsq_<name>`) cover the long tail of questions that no pre-built function anticipated, such as "how many appointments did this patient cancel in the last 6 months?" or "which providers at this location accept this insurance?" A team registers these as parameterized SQL templates that run directly against the workspace's own custom tables. Parameters are typed (string, integer, number, boolean) with optional defaults, and write-time validation rejects multi-statement SQL and session-state commands. Each query runs under the workspace's tenant-scoped database role, keeping access within the workspace's isolation boundary.

Platform functions are read-only. Recording new observations as world model events is done through the dedicated write tools described in [Clinical Tools](/agent/clinical-tools.md) and the [World Model](/data/world-model.md) page, not through this surface.

## Loading Functions at Session Start

Registered functions and workspace data queries are loaded at session start from the workspace's function store. Any registered function or query that carries a description becomes an agent tool, with that description serving as the tool description the agent sees. Availability is then gated per context graph state through `tool_call_specs`.

## Using Functions in Context Graphs

Platform functions are available through `tool_call_specs` on context graph states. A state that needs entity confidence data adds the function to its spec:

```yaml
tool_call_specs:
  - tool_id: fn_entity_confidence
  - tool_id: wsq_appointment_history
    additional_instruction: "Look up the patient's appointment history when relevant"
```

Named platform functions use the `fn_` prefix, becoming `fn_{name}` (e.g., `fn_caller_history`, `fn_risk_score`). Workspace data queries use the `wsq_` prefix, becoming `wsq_{name}`.

The same state-gating rules apply: if a function is not in the current state's `tool_call_specs`, the agent cannot see or call it. This keeps function access contextual - a triage state might expose `fn_entity_confidence` and `fn_caller_history`, while a data capture state exposes the relevant workspace data queries.

## Management

### API Endpoints

Platform functions are managed through workspace-scoped endpoints:

| Endpoint            | What It Does                                                                                                                              |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **List functions**  | Returns all registered functions for a workspace                                                                                          |
| **Get function**    | Returns a single registered function by name                                                                                              |
| **Deploy function** | Validates and upserts a function by name. Re-deploying the same name replaces the definition in place - there is no versioning or aliases |
| **Delete function** | Removes the function. For Python and table-valued functions this also drops the associated compute artifact                               |
| **Invoke function** | Executes a registered function with caller-supplied input and returns its rows                                                            |
| **Test function**   | Executes a function with sample input and records the last-test status, error, and timing on the function                                 |

Functions registered in one workspace are independent of other workspaces.

### Agent Forge CLI

[Agent Forge](/reference/agent-forge.md) provides function management commands:

```
forge platform function list       # List registered functions
forge platform function get        # Show a single function by name
forge platform function deploy     # Validate and upsert a function by name
forge platform function test       # Test with sample input
forge platform function delete     # Remove a function
```

## How Tool Types Relate

The platform has three complementary tool types. Each serves a different purpose:

|                      | Platform Functions                                                 | Actions                                                                | Skills                                                                           |
| -------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Definition**       | Declarative (SQL, AI, Python, table-valued)                        | Imperative (custom code packages)                                      | LLM-backed micro-agents with prompt-based configuration                          |
| **Deployment**       | Register and run - no container or build step                      | Package with dependencies, deploy to execution environment             | Configure via prompt and execution tier                                          |
| **Data access**      | Cross-domain: live entities + analytical aggregations in one query | Single-system: connect to one external system per action               | Depends on execution tier                                                        |
| **Write capability** | None - read-only; writes go through dedicated write tools          | Any external system (EHR write-back, email, document generation)       | Delegated through tool calls or UI automation                                    |
| **Latency**          | Compute cold start possible (covered by filler audio on voice)     | Low-latency execution                                                  | Varies by tier - seconds for orchestration, minutes for desktop automation       |
| **Best for**         | Data retrieval, scoring, classification, summarization             | Multi-step workflows, external system integration, document generation | Complex reasoning, desktop automation, multi-system workflows requiring judgment |

Use platform functions when the agent needs data or computation. Use Actions when the agent needs to perform a specific operation in an external system. Use Skills when the task requires LLM reasoning, multi-step judgment, or interaction with systems that lack APIs.

### Skill Execution Tiers

Skills run on one of five execution tiers that determine how the skill performs its work:

| Tier             | API Value      | What It Does                                                           | Example                                                                             |
| ---------------- | -------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **Direct**       | `direct`       | Single LLM call with no tool use. Fastest execution.                   | Classification, entity extraction, simple Q\&A                                      |
| **Orchestrated** | `orchestrated` | Multi-turn LLM with tool calls, managed by the platform. Default tier. | Multi-step data gathering, API calls, care plan generation                          |
| **Autonomous**   | `autonomous`   | Extended agent loop with checkpointing for long-running tasks          | Complex research, multi-system coordination, document assembly                      |
| **Browser**      | `browser`      | Browser automation with domain allowlisting                            | Navigating EHR web portals, checking insurance eligibility on payer websites        |
| **Computer Use** | `computer_use` | Desktop application automation for systems without APIs                | Interacting with legacy desktop applications, filling forms in systems without APIs |

The Browser and Computer Use tiers enable agents to interact with systems that lack APIs. Browser automation works with web portals scoped to allowed domains. Computer Use extends this to full desktop applications: the agent observes the screen, performs actions such as clicking and typing, and returns structured results to the calling agent.

Three intelligence layers improve reliability on multi-step desktop tasks:

* **Context management** - Old screenshots are compacted to text descriptions while retaining the most recent images, enabling long-horizon tasks that would otherwise exhaust the model's context window
* **Reflection** - Between automation rounds, the system evaluates whether the task is progressing, stuck in a loop, or complete. Stuck tasks are terminated after repeated failures rather than looping indefinitely.
* **Screen analysis** - UI elements and error states are extracted from screenshots and provided as structured hints, improving click accuracy on complex forms and multi-panel layouts

All tiers run with the same confidence and audit controls. Actions taken through desktop automation carry appropriate confidence scores and flow through the same review pipeline.

{% hint style="info" %}
**See also**

* [World Model](/data/world-model.md) for how events and entities work
* [World Model Deep Dive](/data/world-model.md) for write scope isolation details
* [Clinical Tools](/agent/clinical-tools.md) for built-in patient lookup, scheduling, and insurance tools
* [Context Graphs](/agent/context-graphs.md) for how tool availability is state-gated
  {% endhint %}


---

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

```
GET https://docs.amigo.ai/agent/platform-functions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.