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

# Use Foundry functions in workflows and agents

> Call published Foundry functions from Ravenna workflows and AI agents to run custom code actions, integrations, and data lookups in your automations.

Once you publish a Foundry function, it's available in two places: as a step in a workflow, and as a tool your AI agents can use. A single function you build once works in both.

***

## In workflows

Published functions show up in the workflow builder alongside built-in actions.

<Steps>
  <Step title="Open a workflow">
    Go to **Workflows** and open or create a workflow.
  </Step>

  <Step title="Add the function as a step">
    In the step picker, find your function under **Code Actions**.
  </Step>

  <Step title="Map the inputs">
    Each function has input fields. Connect them to data from the workflow trigger or earlier steps. For example, map a ticket's requester email to the function's "email" input.

    For secret-typed inputs (API keys, tokens, passwords), select a credential from your organization's <Tooltip headline="Vault" tip="Encrypted credential storage for API keys and secrets" cta="Learn about Vault" href="/documentation/platform/organizations/vault">Vault</Tooltip> instead of pasting the value. The workflow stores only a reference to the credential. Ravenna decrypts the value in memory when the function runs and scrubs it from execution logs. This works for secret fields at any nesting depth, including inside objects and arrays. Pasting a plaintext value directly still works.
  </Step>

  <Step title="Use the outputs">
    The function's output is available to every step after it. Functions support two output formats:

    * **Text**: Returns a plain text string. The entire output is a single value downstream steps can reference.
    * **JSON**: Returns structured JSON data. Each top-level key in the returned object becomes a separately addressable output field. For example, if your function returns `{ "userId": "abc", "plan": "pro" }`, downstream steps can reference `userId` and `plan` individually.

    Select the output format in the function's **Configure** tab. When JSON output is selected, your code's return value is parsed as JSON automatically.
  </Step>
</Steps>

### Example

A common pattern is enriching a ticket with information from another tool:

1. **Trigger:** A new ticket is created.
2. **Foundry function:** Look up the requester in your CRM by email and return their company and plan.
3. **Update ticket:** Set custom fields with the CRM data and route the ticket based on the plan.

***

## With AI agents

Agents in your workspace can use published functions automatically. When a user asks something a function can help with, the agent calls it.

You can also point agents at specific functions in your <Tooltip tip="Natural language instructions that define agent behavior." headline="Agent rules" cta="Learn about agent rules" href="/documentation/automate/agents/configure">agent rules</Tooltip>. Reference a function by name with `@Function Name`:

<Prompt description="When a user asks about a customer, use @Look up CRM contact to find their details by email. Share the company, role, and plan with the user.">
  When a user asks about a customer, use @Look up CRM contact to find their details by email. Share the company, role, and plan with the user.
</Prompt>

You don't need to write any agent-facing documentation. When you publish a function, Foundry generates an AI tool prompt that tells agents what it does and when to use it. You can regenerate that prompt at any time from the function's **Configure** tab.

### Functions with secret inputs

A function can declare a `secret` input, such as an API key the function passes to an external service. Agents never generate secret values. Before an agent can use a function with a secret input, you must pin each secret input to a <Tooltip tip="Encrypted credential storage at the organization level." headline="Vault" cta="Learn about Vault" href="/documentation/platform/organizations/vault">Vault</Tooltip> credential in the rule editor:

<Steps>
  <Step title="Enable the function in a rule">
    Open the rule, and enable the function in the rule's tool list.
  </Step>

  <Step title="Open Input settings">
    Expand the **Input settings** disclosure under the enabled tool. Each secret input appears with a **required** marker until it's pinned.
  </Step>

  <Step title="Pin each secret to a Vault credential">
    Select a Vault credential for each secret input. If your Vault is empty, add a credential under **Settings** > **Vault** first, then pick it here.
  </Step>

  <Step title="Save the rule">
    Save the rule. Ravenna blocks saving while an enabled function still has an unpinned secret input, since the agent would refuse to load the function at runtime.
  </Step>
</Steps>

Pinned inputs are removed from the schema the agent sees. The agent fills in the remaining inputs, and Ravenna injects the pinned credential when the function executes. The rule stores only a reference to the Vault credential, never the plaintext value.

<Note>
  Only top-level secret inputs can be pinned. A function with a secret field nested inside an object input cannot be used by agents. It remains fully usable in workflows.
</Note>

See [tool input settings](/documentation/automate/agents/configure#tool-input-settings) for details on how pinning works in rules.

<Callout icon="sparkles" color="#7C3AED">
  See how teams wire published functions into real workflows and agent rules in the [Foundry examples](/guides/how-to/foundry/examples) guide.
</Callout>

***

## Who sees a function

A function is visible to the same workspaces its integrations are.

| Integration type | Where the function is available |
| - | - |
| Custom API integration | The workspace it was created in |
| OAuth provider | Every workspace in your organization |

For functions that use more than one integration, the most restrictive scope wins.

***

## Managing published functions

* **Unpublish** removes the function from workflows and agents. Workflows already running finish, but new runs won't start.
* **Update and republish** pushes a new version. Workflows and agents pick it up automatically.
* **Regenerate the AI tool prompt** if you've changed what the function does and want agents to learn the new behavior.

<Callout icon="link" color="#6B7280">
  Learn more about [building workflows](/documentation/automate/workflows/overview) and [configuring AI agents](/documentation/automate/agents/configure).
</Callout>


## Related topics

- [Publish a Foundry action for use in workflows](/api/foundry/publish-a-foundry-action-for-use-in-workflows.md)
- [Build Foundry functions](/documentation/automate/foundry/actions.md)
- [Foundry overview](/documentation/automate/foundry/overview.md)
- [Foundry examples](/guides/how-to/foundry/examples.md)
- [Foundry guide](/guides/how-to/foundry/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.