Connect Cortex to AI Agents: Orchestrate Integrated Workflows

You want to connect Cortex to an AI agent so your internal systems can independently audit service catalogs, map complex dependencies, evaluate governance scorecards, and retrieve recent deployments. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to manually code dozens of API wrappers or maintain fragile custom integrations. Using a unified API for LLM function calling simplifies this process significantly.

Giving a Large Language Model (LLM) read and write access to your Internal Developer Portal (IDP) is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands Cortex's specific tagging semantics and YAML evaluation logic, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting Cortex to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Cortex to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them directly to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Cortex, bind them natively to an LLM using standard tool-calling patterns, and execute complex platform engineering workflows. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

The Engineering Reality of Custom Cortex Connectors

Building AI agents is easy. Connecting them to external SaaS APIs in production is hard. Giving an LLM access to a developer portal sounds simple in a prototype - you write a Node.js function that makes a fetch request and wrap it in an @tool decorator. But when applied to an ecosystem as interconnected as Cortex, this approach collapses entirely.

If you decide to build a custom Cortex integration yourself, you own the entire API lifecycle. Cortex's API introduces several highly specific integration challenges that break standard LLM assumptions.

The Identifier and Tagging Maze

Most REST APIs use a simple UUID or integer as a primary key. Cortex operates on a highly flexible, string-based tagging system (tag_or_id). An entity might be referenced by a standard ID, but it is far more common for engineering teams to reference services by a custom tag (e.g., my-billing-service). When an agent attempts to create a dependency edge between two services, it must know exactly how to format the caller_tag and callee_tag. If an LLM hallucinations a standard UUID where a string tag is required, the API call will fail gracefully, but the dependency map will remain broken.

Scorecard Evaluation Complexity

Scorecards in Cortex are not simple boolean flags. They are complex YAML-driven rule engines. An LLM cannot just "read" a service's maturity. To understand a service's standing, an agent must trigger an evaluation, retrieve the scores, and then separately parse the nextSteps array to figure out exactly which rules the service is failing (e.g., "missing runbook link" or "outdated PagerDuty integration"). Teaching an LLM the multi-step orchestration required to evaluate, read, and interpret a Cortex scorecard requires intense prompt engineering and strict schema enforcement if done manually.

Dangerous Bulk Operations

Cortex provides immensely powerful bulk endpoints, such as cortex_deploy_delete_all_for_all or cortex_catalog_entity_bulk_delete. In an agentic context, handing these raw, unconstrained endpoints to a reasoning engine is a massive risk. If a custom agent misunderstands a user prompt like "clean up the failed deploys," it might issue a command that drops the entire deployment history across the tenant. You must build strict, intermediate translation layers to constrain the LLM's operational blast radius.

How Truto Normalizes Cortex for AI Agents

Instead of hardcoding a custom wrapper for every Cortex endpoint, developers can leverage Truto. Every integration on Truto is represented as a comprehensive JSON object mapping the underlying product's API behavior.

Integrations are broken down into Resources (which map to Cortex endpoints) and Methods (the operations available on those endpoints). These Methods operate as Proxy APIs. Truto handles the authentication, payload validation, and query parameter processing, returning data in a predefined, reliable format.

To make this agent-ready, Truto provides the /integrated-account/<id>/tools endpoint. This API returns all available Proxy APIs along with optimized descriptions and schemas. Your LLM framework simply ingests this JSON array and automatically understands how to interact with Cortex - no custom routing required.

A Note on Rate Limits and Backoff

It is critical to understand how Truto handles upstream limits. When an LLM executes a loop that triggers a high volume of tool calls against Cortex, you will eventually hit rate limits.

Truto does not absorb these rate limits, throttle requests, or apply automatic backoff. When the Cortex API returns an HTTP 429 Too Many Requests, Truto passes that error directly back to your agent. However, Truto normalizes the upstream rate limit information into standard IETF headers:

• ratelimit-limit
• ratelimit-remaining
• ratelimit-reset

The caller (your agent framework) is fully responsible for intercepting the 429 response, reading the ratelimit-reset header, pausing execution, and retrying. We will cover how to build this resilience in the code section below.

Hero Tools for Cortex Orchestration

When you connect Cortex to an LLM via Truto, your agent gains access to dozens of capabilities. Here are the most critical operations for platform engineering and governance workflows.

list_all_cortex_catalog_entity

This is the core discovery tool. It allows the agent to retrieve a paginated list of all entities across the Service, Resource, and Domain Catalogs. It returns deep metadata including owners, git links, Slack channels, and hierarchy data.

"Find all services in the catalog that are currently missing a defined owner and return their tags."

cortex_dependency_list_for_entity

Understanding the blast radius of an incident requires mapping dependencies. This tool allows the agent to input a caller_tag and retrieve all upstream and downstream dependencies, including the specific methods and paths they communicate over.

"What other services depend on the payment-gateway service? List their tags and the specific API paths they rely on."

cortex_scorecard_get_next_steps_for_entity

To automate governance, an agent needs to know exactly how a service can improve. This tool retrieves the specific remaining rules a Cortex entity must complete to advance to the next scorecard level.

"Check the production-readiness scorecard for user-auth-service. What exact steps are required for it to reach the Gold tier?"

cortex_deploy_list_for_entity

During an incident or audit, agents need to verify recent changes. This tool lists the deployment history for a specific entity, returning details like environment, git SHA, timestamp, and deployer email.

"Get the last five deployments for the inventory-api in the production environment. Who triggered the most recent deploy?"

cortex_on_call_get_current_for_entity

When an automated alert requires human intervention, the agent needs to know who to ping. This tool fetches the current on-call schedule details associated with a specific Cortex entity.

"Who is currently on-call for the checkout-service? Give me their contact details based on the current escalation tier."

cortex_entity_doc_get_openapi

Agents tasked with writing integration code or validating API contracts can use this tool to pull the raw OpenAPI specification attached to a specific Cortex entity.

"Retrieve the OpenAPI specification for the notification-service. Does it currently define a POST endpoint for sending SMS?"

To see the complete inventory of available capabilities - including custom data ingestion, scorecard evaluation triggers, and team hierarchy management - visit the Cortex integration page.

Workflows in Action

Exposing individual tools to an LLM is powerful, but the real value emerges when agents autonomously chain these tools together to execute multi-step platform engineering workflows. Here are two concrete examples of how developers are using these tools in production.

Scenario 1: The Automated Governance Enforcer

Platform teams spend countless hours chasing developers to update documentation and ownership. An autonomous agent can run daily to enforce these standards.

"Scan the entire service catalog for any entities in the 'payments' domain that have not achieved 'Silver' status on the Security Scorecard. For each failing service, find the current on-call engineer and generate a Slack message detailing the exact steps they need to take to fix their score."

Step-by-step execution:

1. The agent calls list_all_cortex_catalog_entity filtering for the 'payments' domain.
2. For each returned entity, it calls cortex_scorecard_get_next_steps_for_entity targeting the Security Scorecard.
3. If the entity is failing rules, the agent calls cortex_on_call_get_current_for_entity to identify the responsible engineer.
4. The agent compiles the rulesToComplete into a formatted message for the engineer.

Result: The platform team completely automates governance nagging. Engineers receive highly specific, actionable messages indicating exactly what YAML lines or integrations need fixing, dramatically improving overall catalog maturity.

Scenario 2: The Incident Blast-Radius Analyzer

When a critical service goes down, incident commanders need immediate context on upstream impacts and recent changes.

"The auth-proxy service is currently throwing 500s. Find all services that depend on auth-proxy, check if any of those dependent services were deployed in the last 2 hours, and list the commit SHAs for those recent deployments."

Step-by-step execution:

1. The agent calls cortex_dependency_list_for_entity using auth-proxy as the target to retrieve a list of all caller services.
2. The agent loops through the returned caller tags.
3. For each caller tag, it executes cortex_deploy_list_for_entity.
4. The LLM filters the returned deployment arrays for timestamps within the last two hours, extracting the specific sha and deployerEmail values.

Result: The incident commander is instantly handed a correlated list of suspect deployments across the entire microservice ecosystem, reducing Mean Time to Resolution (MTTR) by eliminating manual dashboard hopping.

Building Multi-Step Workflows

To build these autonomous workflows, you need a programmatic way to fetch Cortex tools, bind them to your LLM, and orchestrate the execution loop. Because Truto's /tools endpoint relies on standard JSON Schema, this approach works seamlessly with LangChain, LangGraph, CrewAI, Vercel AI SDK, MCP servers, or custom control loops.

Below is a conceptual architecture using TypeScript, demonstrating how to fetch the tools, execute a generative loop, and safely handle Cortex rate limits.

sequenceDiagram
    participant App as "Your Application"
    participant LLM as "LLM (OpenAI/Claude)"
    participant Truto as "Truto Tools API"
    participant Cortex as "Cortex API"
    
    App->>Truto: GET /integrated-account/{id}/tools
    Truto-->>App: Return JSON array of Cortex tools
    App->>LLM: Pass tools via .bindTools()
    App->>LLM: User Prompt<br>"Check dependencies for checkout-service"
    LLM-->>App: ToolCall: cortex_dependency_list_for_entity
    App->>Truto: Execute tool via Proxy API
    Truto->>Cortex: Authenticated API Request
    Cortex-->>Truto: HTTP 429 Too Many Requests
    Truto-->>App: 429 with ratelimit-reset header
    App->>App: Sleep until reset time
    App->>Truto: Retry tool execution
    Truto->>Cortex: Authenticated API Request
    Cortex-->>Truto: 200 OK (Dependencies Data)
    Truto-->>App: Return normalized payload
    App->>LLM: Provide tool execution result
    LLM-->>App: Final natural language response

Handling Truto's Passthrough Rate Limits

As noted earlier, Truto acts as a transparent proxy for API errors. When you execute an agent loop that makes rapid sequential requests (like checking deployments for 50 different catalog entities), Cortex will eventually return an HTTP 429. Truto catches this 429 and passes it directly to your application with normalized headers.

Here is how you handle the tool execution and implement the required backoff logic:

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
// 1. Initialize the LLM
const llm = new ChatOpenAI({
  modelName: "gpt-4o",
  temperature: 0,
});
 
// 2. Initialize Truto Tool Manager for the specific Cortex connection
const toolManager = new TrutoToolManager({
  trutoApiKey: process.env.TRUTO_API_KEY!,
  integratedAccountId: process.env.CORTEX_INTEGRATED_ACCOUNT_ID!,
});
 
// 3. Custom Executor with Rate Limit Handling
async function executeToolWithBackoff(tool, args, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      // Attempt to invoke the tool
      const result = await tool.invoke(args);
      return result;
    } catch (error) {
      // Check if Truto passed back an HTTP 429
      if (error.status === 429) {
        console.warn(`[Rate Limit] Cortex API limit reached.`);
        
        // Read the standard IETF header passed by Truto
        const resetTimeHeader = error.headers['ratelimit-reset'];
        
        if (resetTimeHeader) {
          const resetTimeMs = parseInt(resetTimeHeader, 10) * 1000;
          const waitTime = Math.max(0, resetTimeMs - Date.now());
          
          console.log(`Sleeping for ${waitTime}ms before retry...`);
          await new Promise(resolve => setTimeout(resolve, waitTime));
          continue; // Retry the loop
        }
      }
      // If it's not a 429, or we run out of retries, throw the error
      throw error;
    }
  }
  throw new Error("Max retries exceeded during tool execution.");
}
 
async function runCortexAgent() {
  // 4. Fetch the tools dynamically from Truto
  const tools = await toolManager.getTools();
  
  // Bind the tools to the LLM
  const llmWithTools = llm.bindTools(tools);
  
  const messages = [
    { role: "user", content: "Find all services that depend on the `auth-proxy` service and list their current on-call engineers." }
  ];
 
  // 5. Run the agentic loop
  while (true) {
    const response = await llmWithTools.invoke(messages);
    messages.push(response);
 
    // If the LLM decides it doesn't need any more tools, break the loop
    if (!response.tool_calls || response.tool_calls.length === 0) {
      break;
    }
 
    // 6. Execute the tools requested by the LLM
    for (const toolCall of response.tool_calls) {
      const selectedTool = tools.find(t => t.name === toolCall.name);
      if (selectedTool) {
        console.log(`Executing tool: ${selectedTool.name}`);
        
        // Use our resilient executor
        const toolResult = await executeToolWithBackoff(selectedTool, toolCall.args);
        
        messages.push({
          role: "tool",
          tool_call_id: toolCall.id,
          content: JSON.stringify(toolResult)
        });
      }
    }
  }
 
  console.log("Agent Final Response:", messages[messages.length - 1].content);
}
 
runCortexAgent().catch(console.error);

This pattern ensures that your platform engineering agents are resilient. By dynamically fetching tools, your agent always has the latest schema definitions for Cortex endpoints. By implementing an execution wrapper that reads ratelimit-reset, your workflows can pause and safely navigate the reality of high-volume API orchestration without crashing.

If you want to move beyond simple chatbots and start deploying autonomous agents that actively manage your infrastructure, service catalogs, and deployment lifecycles, the integration layer is your biggest bottleneck. By leveraging Truto's /tools endpoint, you abstract away authentication, pagination, and schema mapping, allowing your engineering team to focus entirely on building superior reasoning loops and solving actual business problems.