# Platform Functions

{% hint style="info" %}
**API Name**: Platform functions are managed through the `functions` endpoints on each workspace. 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/diagram content="flowchart LR
agent\["Agent mid-conversation"] --> fn{Function Type}
fn --> sql\["SQL\n(query live + analytical data)"]
fn --> py\["Python\n(custom logic)"]
fn --> ai\["AI\n(classify, extract, summarize)"]
sql --> result\["Structured result\nback to agent"]
py --> result
ai --> result" %}

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

### Named Functions

Named functions are pre-built queries or computations registered in the function catalog. 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 Table**        | Returns rows from a parameterized query across live and analytical data                 | Patient summary, caller history, entity confidence assessment                                  |
| **SQL Scalar**       | Returns a single computed value                                                         | Risk score, formatted phone number                                                             |
| **Python UDF**       | Runs Python logic on the compute layer                                                  | Address parsing, custom scoring algorithms                                                     |
| **AI Built-in**      | Composes built-in AI operations (classify, summarize, extract, mask, analyze sentiment) | Intent classification, clinical extraction, transcript cleanup, PII redaction                  |
| **Foundation Model** | Calls a foundation model with patient context to generate complex outputs               | Care plan generation, operator handoff summaries, medical term translation, urgency assessment |

The platform ships with built-in functions and discovers additional functions from the workspace's compute catalog at runtime.

{% 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, the platform discovers additional functions from the workspace's compute catalog. Catalog functions span AI operations (intent classification, clinical extraction, PII redaction, sentiment analysis), foundation model reasoning (care plan generation, handoff summaries, urgency assessment, medical translation), and Python UDFs (risk scoring, phone formatting, address parsing). The available set depends on what the workspace has provisioned. New functions registered in the catalog auto-discover into the agent's toolset without redeployment.

### Open Query

The open query tool (`fn_query`) lets the agent write any read-only SQL at runtime. Instead of calling a pre-built function, the agent constructs the query itself based on conversation context.

This is for the long tail - questions that no pre-built function anticipated. "How many appointments did this patient cancel in the last 6 months?" or "Which providers at this location accept this insurance?" The agent writes the SQL, the platform validates it (read-only, auto-limited to 100 rows), and executes it.

The SQL is validated before execution:

* Only SELECT and WITH (CTE) statements are allowed
* DML keywords (INSERT, UPDATE, DELETE, DROP, etc.) are rejected
* Results are automatically capped at 100 rows
* Queries run within workspace isolation boundaries

### Open Write

The open write tool (`fn_write`) lets the agent record new observations as world model events when no specific write tool exists for the situation. The agent provides an entity ID, event type, domain, structured data, and an optional confidence level.

This follows the same write path as all other world model writes:

* Events are inserted atomically with entity state recomputation
* [Write scope](/data/world-model.md) is enforced - the agent can only write to entities it has identified in the current session
* Default confidence is 0.3 (agent inference level)
* Events are eligible for outbound sync through the connector runner

The open write tool is for observations that fall outside the [clinical tools](/agent/clinical-tools.md) - a patient preference noted during conversation, a concern raised that does not map to an existing event type, or context captured from an unusual workflow.

## Catalog Discovery

Functions do not have to be manually registered one at a time. The platform can auto-discover functions from the compute catalog. Any function with a description becomes an agent tool automatically - the description serves as the tool description the agent sees.

Discovery runs at session initialization. Three sources are merged by priority:

1. **Catalog discovery** - Functions found in the catalog with descriptions (lowest priority)
2. **Built-in defaults** - The platform's built-in functions with curated input schemas
3. **Workspace-registered** - Functions explicitly registered through the API (highest priority)

Higher-priority sources override lower ones by name. This means a workspace can customize a built-in function's description or input schema by registering its own version, while catalog-discovered functions provide a baseline of everything available.

{% hint style="info" %}
**Zero-Registration Path**: Write a function with a descriptive comment in the catalog. Next time an agent session starts, that function is available as a tool. No API calls, no configuration changes.
{% endhint %}

## 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: fn_query
    additional_instruction: "Query world model data when no existing tool fits"
  - tool_id: fn_write
    additional_instruction: "Record new observations as world events"
```

All platform function tool IDs use the `fn_` prefix. Named functions become `fn_{name}` (e.g., `fn_caller_history`, `fn_risk_score`). The open query and write tools are `fn_query` and `fn_write`.

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 `fn_write`.

## Management

### API Endpoints

Platform functions are managed through workspace-scoped endpoints:

| Endpoint              | What It Does                                                                                              |
| --------------------- | --------------------------------------------------------------------------------------------------------- |
| **List functions**    | Returns all registered functions for a workspace                                                          |
| **Register function** | Adds a new function to the workspace. The function must already exist in the compute catalog              |
| **Delete function**   | Removes the workspace registration. The underlying function is not affected                               |
| **Test function**     | Executes a function with sample input and returns the result with timing                                  |
| **Discover catalog**  | Queries the catalog to find all available functions with descriptions. Shows which are already registered |
| **Sync catalog**      | Auto-registers all discovered catalog functions that are not already registered                           |
| **Query**             | Executes an open-scope read-only SQL query                                                                |

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 register   # Register a new function
forge platform function test       # Test with sample input
forge platform function delete     # Remove registration
forge platform function query      # Run an open SQL query
forge platform function catalog    # Discover available functions
forge platform function sync       # Auto-register all discovered functions
```

## How Tool Types Relate

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

|                      | Platform Functions                                                 | Actions                                                                | Skills                                                                           |
| -------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **Definition**       | Declarative (SQL, Python, AI composition)                          | 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** | World model events only (via `fn_write`)                           | 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`      | Headless browser automation with domain allowlisting                   | Navigating EHR web portals, checking insurance eligibility on payer websites        |
| **Computer Use** | `computer_use` | Full desktop automation via browser, RDP, or VNC connections           | 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 using headless browser sessions scoped to allowed domains. Computer Use extends this to full desktop applications - the agent connects to a desktop session (browser, remote desktop, or VNC), receives screenshots, performs actions (clicking, typing, navigating), and returns structured results to the calling agent.

For Windows RDP connections, Computer Use supports enterprise network configurations: RD Gateway traversal for reaching desktops behind firewalls, RemoteApp mode for single-application access (launching one EHR application rather than a full desktop), and terminal farm load balancing for connecting to pools of application servers. Connection health is monitored between automation rounds with automatic reconnect on transient failures.

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**

* [Actions](/agent/platform-functions.md) for custom code packages that handle multi-step workflows and external system integration
* [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: 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.