Connect Riza to AI Agents: Orchestrate Code Tools and Project Secrets

You want to connect Riza to an AI agent so your system can independently execute code, deploy custom sandboxed runtimes, manage project secrets, and orchestrate complex scripting tasks. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and host custom integration layers manually.

Giving a Large Language Model (LLM) the ability to execute arbitrary code is a massive leap in agentic capabilities, but it introduces severe engineering complexities. You either spend weeks building secure isolation layers, managing execution timeouts, and translating complex JSON schemas, or you use a managed infrastructure layer that handles the API boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Riza to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Riza to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these code-execution tools and bind them natively to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Riza, bind them to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and orchestrate secure code-execution workflows. For a deeper look at the architectural patterns behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of Custom Riza Connectors

Building an AI agent is easy. Connecting that agent to a highly specialized code-execution API like Riza is hard. Giving an LLM access to write and run code sounds simple during a local prototype. You write a Node.js function that makes a fetch request to an endpoint and wrap it in an @tool decorator. In production, this naive approach collapses entirely.

If you decide to build a custom integration for Riza, you own the entire API lifecycle. Riza is not a standard CRUD application - it is an execution environment API. This introduces several specific integration challenges that break standard LLM assumptions.

The Execution Payload and Output Separation

Unlike standard SaaS APIs that return a clean, unified JSON object representing a customer or an invoice, Riza's execution endpoints return operational data. When you submit a script to Riza, the API does not just return a string containing the result. It returns a complex object consisting of exit_code, stdout, stderr, and duration.

LLMs consistently struggle with parsing execution output if they are not explicitly trained to look for stderr when exit_code is non-zero. If an agent writes a Python script that throws a syntax error, stdout will be empty, and the error trace will be in stderr. If you hand-code your connector, you have to write extensive wrapper logic to detect non-zero exit codes, merge stderr into the LLM's observation window, and format the output so the agent realizes it made a mistake and needs to rewrite the code. Truto handles this mapping natively via Proxy APIs, ensuring the LLM receives the execution payload in a structured format it inherently understands.

Dependency Isolation and Runtime Manifests

LLMs often hallucinate dependencies. An agent might write a Python script that assumes the requests library or pandas is globally available. In Riza's sandboxed environment, dependencies must be explicitly defined using runtime manifests and additional Python imports.

When an agent wants to execute a complex script, it cannot simply hit a generic execution endpoint. It must first provision a specific runtime environment via the Riza API, define the required language engines, and specify the manifest file. Building custom tools to teach an LLM this multi-step provisioning process requires massive prompt engineering. You have to explain to the agent that before calling a command, it must first query the runtimes list, create a new runtime if needed, and wait for its deployment status. Truto's auto-generated tool descriptions and standardized query schemas provide this dependency context automatically, forcing the LLM to provide the correct inputs without manual prompt hacking.

Rate Limits and Execution Boundaries

Executing arbitrary code is resource-intensive. Like any infrastructure provider, Riza enforces rate limits and concurrent execution boundaries. If an agent gets stuck in a loop - writing code, executing it, failing, and immediately trying again - it will rapidly exhaust the API limits.

Handling rate limits in an agentic loop requires careful architectural decisions. Factual note on rate limits: Truto does not retry, throttle, or apply backoff on rate limit errors automatically. When an upstream API like Riza returns an HTTP 429 Too Many Requests, Truto passes that error directly back to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification (see Truto Rate Limits). The caller - in this case, your agent framework or worker node - is completely responsible for inspecting these standardized headers and implementing the appropriate retry or backoff logic. Do not build an agent assuming the infrastructure layer will absorb execution limits for you.

Connecting Riza to AI Agents via Truto

Instead of manually coding API wrappers for every Riza endpoint, Truto maps any underlying product's API into a REST-based CRUD API using a concept of Resources and Methods. These Methods - handling authentication, query parameter processing, and pagination - are exposed as Proxy APIs.

For AI agents, Truto takes this a step further. We call the /integrated-account/<id>/tools endpoint on the Truto API to return all of these Proxy APIs with their exact descriptions and JSON schemas, instantly converting them into tools that an LLM framework can consume. This functionality makes Truto one of the best unified APIs for LLM function calling and AI agent tools available today.

sequenceDiagram
  participant Agent as Agent Framework
  participant TrutoAPI as Truto API
  participant RizaAPI as Riza API

  Agent->>TrutoAPI: GET /integrated-account/<id>/tools
  TrutoAPI-->>Agent: Return standardized tool JSON schemas
  Agent->>Agent: Bind schemas to LLM
  Agent->>TrutoAPI: Execute tool (e.g., create_a_riza_code_execution)
  TrutoAPI->>RizaAPI: POST execution payload with auth
  RizaAPI-->>TrutoAPI: Return stdout, stderr, exit_code
  TrutoAPI-->>Agent: Normalized JSON response
  Agent->>Agent: Parse execution output

Because Truto normalizes the schema mapping dynamically, any updates Riza makes to their execution API are reflected immediately in the tool schemas passed to your agent.

Core Riza Agent Tools

Truto exposes the entirety of the Riza API to your agents. Here are the highest-leverage operations for orchestrating code execution.

Create a Riza Code Execution

The most fundamental tool. This allows the agent to execute a raw code script by submitting it in a specified programming language. It returns the exact execution result, giving the agent immediate feedback on its logic.

"Write a Python script to calculate the Fibonacci sequence up to the 50th number. Run the script using the create_a_riza_code_execution tool and tell me the output. If it fails, look at the stderr output and fix the code."

Create a Riza Runtime

When an agent needs a specific environment - perhaps requiring external libraries or a different language engine - it uses this tool to provision a new runtime inside the Riza project.

"I need to process some CSV data using pandas. Use the create_a_riza_runtime tool to spin up a new Python environment, ensuring you define a manifest file that includes the pandas library. Let me know the new runtime ID when it is ready."

Create a Riza Tool

This is a highly meta operation. Instead of just running a script once, the agent can write a piece of code, define its input schema, and save it as a persistent tool within Riza. This allows agents to build their own utility libraries for future executions.

"Write a JavaScript function that accepts a URL string as an input and extracts the domain name. Save this function permanently by calling the create_a_riza_tool operation. Provide a clear description and input_schema so other agents know how to use it."

Create a Riza Secret

Agents frequently need to interact with external APIs from within their Riza scripts. This tool allows the agent to securely inject API keys or tokens into the Riza project environment so the executed code can access them without hardcoding credentials.

"We need to fetch data from the Stripe API in our next script. Take this API key and store it securely using the create_a_riza_secret tool under the name 'STRIPE_PROD_KEY'."

Create a Riza Command

For more complex infrastructure tasks, this tool executes a script in Riza's secure, isolated sandbox environment and returns the full stdout, stderr, and duration. It is ideal for running shell-like commands or executing complex system-level logic.

"Execute a command in the sandbox to print the current environment variables. Use the create_a_riza_command tool and ensure you capture both stdout and stderr in your response."

For the complete inventory of available Riza tools and detailed input/output schemas, refer to the Truto Riza Integration Page.

Workflows in Action

Giving an agent isolated code execution capabilities enables autonomous workflows that would otherwise require dedicated microservices. Here are two real-world examples of how engineering teams use Riza tools via Truto.

Autonomous Data Transformation Pipeline

Data engineers often face scenarios where unstructured data needs highly specific, custom parsing logic that changes per customer. An agent can read the data, write a custom parsing script, and execute it entirely in isolation.

"Look at this raw customer JSON payload. The data schema is completely non-standard. Write a Python script to normalize this payload into our standard User object. Spin up a Riza runtime, inject the raw payload as a variable, execute the script, and return the clean JSON output."

Step-by-step execution:

1. The agent analyzes the unstructured JSON payload.
2. It generates a Python script containing the specific transformation logic.
3. It calls create_a_riza_code_execution, passing language: "python" and the generated code.
4. Riza runs the script in the sandbox. Truto returns the stdout and exit_code.
5. If the script fails (e.g., exit_code: 1), the agent reads the stderr from the Truto response, patches its script, and calls create_a_riza_code_execution again.
6. The agent returns the transformed, standardized data to the user.

Persistent Agentic Tool Generation

Instead of relying entirely on predefined API connectors, agents can write custom integrations on the fly, save them into Riza, and invoke them later.

"We need a reliable way to query the public Hacker News API for top stories. Write a robust Node.js function that fetches the top 10 stories, parses their titles, and returns an array. Save this as a permanent tool in our project so other workflows can invoke it later without rewriting the code."

Step-by-step execution:

1. The agent writes the Node.js implementation for querying Hacker News.
2. It drafts a JSON schema defining the inputs (e.g., limit of stories).
3. It calls the create_a_riza_tool endpoint via Truto, passing the name, language, code, and input_schema.
4. Truto proxies the request to Riza, which creates the permanent tool and returns a revision_id.
5. In future workflows, agents can simply call create_a_riza_tool_execution using the saved tool_id to run the logic instantly.

Building Multi-Step Workflows

To execute these complex loops programmatically, you must fetch the tool schemas from Truto's /tools endpoint and bind them to your LLM framework. The example below demonstrates how to use the Truto Langchain.js SDK (TrutoToolManager) to retrieve Riza tools, pass them to an Anthropic model, and handle the execution loop. For developers scaling to more complex setups, we've also covered handling auth and tool sharing in multi-agent frameworks via MCP to ensure secure tool distribution.

import { ChatAnthropic } from "@langchain/anthropic";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
async function runRizaExecutionAgent(rizaAccountId: string) {
  // 1. Initialize the Truto Tool Manager
  const toolManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY,
  });
 
  // 2. Fetch all Riza tools for this specific integrated account
  let tools;
  try {
    tools = await toolManager.getTools(rizaAccountId);
  } catch (error) {
    console.error("Failed to fetch tools from Truto API.");
    throw error;
  }
 
  // 3. Initialize the LLM and bind the Riza tools
  const llm = new ChatAnthropic({
    modelName: "claude-3-5-sonnet-latest",
    temperature: 0,
  }).bindTools(tools);
 
  // 4. Define system instructions focusing on safe code execution
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", `You are an elite DevOps AI agent connected to a Riza sandbox.
      You have the ability to write and execute arbitrary code.
      If you need to run code, use the create_a_riza_code_execution tool.
      Always check the exit_code of your execution. If the exit_code is not 0,
      carefully read the stderr output to diagnose your failure, then rewrite 
      your code and try again. Do not return failure to the user without retrying.`],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 5. Create the Agent and Executor
  const agent = createToolCallingAgent({ llm, tools, prompt });
  const executor = new AgentExecutor({ 
    agent, 
    tools, 
    maxIterations: 5 // Prevent infinite loops if code continuously fails
  });
 
  // 6. Execute the workflow with try/catch for standard IETF rate limits
  try {
    console.log("Agent starting... Deploying script to Riza.");
    const result = await executor.invoke({
      input: "Write a fast Python script to find all prime numbers up to 1000. Run it and give me the array of numbers."
    });
    
    console.log("Agent finished execution:", result.output);
 
  } catch (error: any) {
    // Inspect Truto's standardized pass-through headers for rate limits
    if (error.response && error.response.status === 429) {
      const resetTime = error.response.headers.get('ratelimit-reset');
      const limit = error.response.headers.get('ratelimit-limit');
      console.warn(`Riza Rate Limit Exceeded. Max executions: ${limit}. Retry after: ${resetTime} seconds.`);
      // Implement your application-specific backoff logic here
    } else {
      console.error("Execution failed due to API or Framework error:", error);
    }
  }
}
 
// Execute the agent
runRizaExecutionAgent("riza_account_12345");

By leveraging the TrutoToolManager, you remove the need to manually build schemas for Riza's execution payloads. The LLM understands inherently what parameters it needs to pass (language, code) and knows how to map the returning stdout and stderr back into its observation loop.

Accelerating AI Agent Development

Building autonomous systems that can safely write and execute code in isolated sandboxes is a monumental engineering task. If you waste cycles hand-coding custom integration wrappers, handling OAuth lifecycles, and managing manual schema drift, you are detracting from core agent development.

Truto's /tools endpoint abstracts away the underlying API complexity of Code-Execution platforms like Riza. By generating native LLM schemas directly from API definitions and normalizing critical signals like upstream rate-limit headers, your team can deploy agentic workflows faster and with significantly less technical debt.