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.

1. Open a workflow

   Go to Workflows and open or create a workflow.

2. Add the function as a step

   In the step picker, find your function under Code Actions.

3. 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 Vault 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.

4. 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.

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 agent rules. Reference a function by name with @Function Name:

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.

CopiedCopy 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 Vault credential in the rule editor:

1. Enable the function in a rule

   Open the rule, and enable the function in the rule’s tool list.

2. Open Input settings

   Expand the Input settings disclosure under the enabled tool. Each secret input appears with a required marker until it’s pinned.

3. 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.

4. 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.

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.

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.

See tool input settings for details on how pinning works in rules.

See how teams wire published functions into real workflows and agent rules in the Foundry examples guide.

---

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.

Learn more about building workflows and configuring AI agents.