Tips for getting the most out of Foundry
Start with the narrowest scopes. It’s easier to add a scope later than to explain to a security review why you asked for the kitchen sink on day one. For Google, prefer the.readonly variants until you actually need to write.
Point the docs URL at the API reference, not the homepage. Research is much better when Foundry can see endpoint pages and OpenAPI specs. For Google APIs, link directly to the reference page for the specific API (Calendar, Gmail, etc.) rather than to developers.google.com.
Use one integration per real-world tool. Keeping Salesforce and HubSpot as separate integrations, instead of a single “CRM”, makes functions easier to understand and lets you swap one out without rewriting the other.
Test in development before publishing. Foundry’s test panel lets you pick the runtime environment. Wire your function against a sandbox tenant in development first so you don’t create real records while iterating.
Give your function a precise description. The description is what AI agents read when they decide whether to call your function. “Look up a customer by email and return their plan and ARR” is much more useful than “get customer data.”
Chat your way to better code. When something isn’t right, ask in plain language: “add pagination,” “retry on 429,” “only return active users.” It works far better than hand-editing the generated TypeScript.
Iterate small. Get the happy path working first, then ask Foundry to add error handling, pagination, or filtering one piece at a time. Each round leaves you with a working function.
Use Configure to keep agent prompts fresh. If you change what a function does, regenerate the AI tool prompt from the function’s Configure tab so agents pick up the new behaviour.
All of the UI surfaces mentioned here (the test panel, the Configure tab, the workspace layout) are covered in the main Building functions reference.
Troubleshooting
OAuth setup
Google returns “redirect_uri_mismatch.” The redirect URI in your OAuth client doesn’t exactly match Ravenna’s callback URL. Confirm the right value with your Ravenna team and paste it back into Google verbatim. Trailing slashes andhttp vs https matter.
The OAuth flow succeeds but the function gets 401s.
The API you’re calling probably isn’t enabled on the Google Cloud project. Go to APIs & Services → Library and enable it, then have the user reconnect.
Tokens stop working after an hour.
For Google, make sure access_type=offline and prompt=consent are set in the authorization URL parameters. Without them, Google doesn’t issue a refresh token and access expires when the access token does. See the Google walkthrough for the exact JSON.
A user disconnected and now functions fail for them.
Have the user reconnect from Settings → Integrations under the Custom category. Their function picks the new connection up automatically.
Docs research
Research fails or returns nothing useful. The docs URL likely points at marketing content. Try the API reference page directly. If the tool has an OpenAPI or Swagger URL, use that instead. Research finishes but generated code uses the wrong endpoints. Either point Foundry at a narrower docs URL (a specific endpoint page) or be more specific in your function description, naming the endpoint or method explicitly.Generation and testing
Generation status is stuck onError.
Open the function workspace and check the error message. It’s usually a clue about a missing scope, a broken docs URL, or an incompatible response shape. Click Regenerate to try again after fixing the cause.
Test runs return data, but workflows show no output.
Make sure the function returns a structured object (e.g. { id, status }) rather than a string. Workflows can only map fields off objects.
The function works in development but fails in production.
Check that the credential you configured covers the production environment. Some tools issue separate keys per environment, and ctx.env gives the function a way to branch. The integration itself still needs to reach the production API.
Publishing
Publish fails on validation. Foundry runs TypeScript and dry-run checks before publishing. Read the error in the publish dialog, which points at the exact line. Ask in chat (“the publish check is failing because X, fix it”) rather than editing by hand. Agents don’t seem to know about a function I just published. New functions are picked up immediately, but if you changed what a function does, regenerate the AI tool prompt from the Configure tab. Agents use that prompt to decide when to call the function.Still stuck? Reach out to your Ravenna team or support@ravenna.ai with the function ID and the error you’re seeing.