---
title: "Connect Firma to AI Agents: Power Embedded Signing & JWT Workflows"
slug: connect-firma-to-ai-agents-power-embedded-signing-jwt-workflows
date: 2026-07-07
author: Riya Sethi
categories: ["AI & Agents"]
excerpt: "Learn how to connect Firma to AI Agents for automated embedded signing, JWT management, and e-signature workflows using Truto's dynamic /tools endpoint."
tldr: "Connect Firma to your AI agents via Truto's /tools API to independently orchestrate embedded signing requests, manage JWTs, and handle document lifecycles without maintaining complex integration wrappers."
canonical: https://truto.one/blog/connect-firma-to-ai-agents-power-embedded-signing-jwt-workflows/
---

# Connect Firma to AI Agents: Power Embedded Signing & JWT Workflows


You want to connect Firma to an AI agent so your internal systems can independently generate contracts, handle embedded signing tokens, revoke JWTs dynamically, and orchestrate complex e-signature operations based on historical context. Here is exactly how to do it using Truto's `/tools` endpoint and SDK, bypassing the need to manually code dozens of endpoints or maintain complex API wrappers.

Giving a Large Language Model (LLM) read and write access to your Firma instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector that understands the strict state machines of signing workflows, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on [connecting Firma to ChatGPT](https://truto.one/connect-firma-to-chatgpt-automate-templates-e-signature-requests/), or if you are building on Anthropic's models, read our guide on [connecting Firma to Claude](https://truto.one/connect-firma-to-claude-manage-workspaces-webhook-automations/). For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Firma, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute autonomous document operations. For a deeper look at the architecture behind this approach, refer to our research on [architecting AI agents and the SaaS integration bottleneck](https://truto.one/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/).

## The Engineering Reality of Custom Firma Connectors

Building AI agents is easy. [Connecting them to external SaaS APIs](https://truto.one/what-is-llm-function-calling-for-integrations-2026-guide/) is hard. Giving an LLM access to external data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in an `@tool` decorator. In production, this approach collapses entirely, especially with an ecosystem as strict as Firma.

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

### The Mutually Exclusive PATCH Trap

Unlike standard CRUD APIs where a `PATCH` request can accept an aggregate payload of all changed fields, Firma strictly limits what can be mutated simultaneously. For example, when updating a signing request via the `firma_signing_requests_partial_update` endpoint, you can update general properties (name, description, expiration) OR you can update a single recipient. You cannot combine both in a single request.

When an AI agent decides a contract needs a new title and a new signer email, it will naturally try to dump both into a single JSON payload. Firma will immediately reject this with a 400 Bad Request. To fix this in a hand-coded integration, you must write complex interceptor logic or highly specific system prompts to force the LLM to split its intentions into sequential tool calls. 

### Ephemeral JWT Lifecycles for Embedded Editors

Firma provides powerful embedded editors for signing requests, powered by short-lived JWTs. The lifecycle of these tokens is strict. An agent must generate the token using the signing request ID, surface the URL to the host application (or interact with it), and critically, it must know when to revoke it. 

Tokens for template embedding expire in 24 hours, while signing request JWTs expire in 7 days. If an agent creates multiple JWTs during a conversational loop without revoking the previous ones, you leak active, privileged sessions. Teaching an agent to manage this state machine - generation, execution, revocation - requires precise tool definitions that explicitly map out the required sequence of operations.

### Strict State-Locked Operations

Firma enforces strict state transitions. You cannot cancel a signing request that hasn't been sent yet. You cannot resend a notification to a recipient who has already signed. Standard LLMs do not inherently understand these state barriers. They will attempt to cancel a `draft` document and crash when the API returns an error.

Your integration layer must clearly define the prerequisites for operations like `firma_signing_requests_cancel` and `create_a_firma_signing_request_resend`, requiring the agent to first query the document status, evaluate the active signers, and only execute the state change if the conditions are met.

## How Truto's Proxy Architecture Solves This

Truto eliminates these challenges by providing dynamic, pre-configured tools directly to your agent framework via the `/tools` endpoint. Instead of hardcoding standard [MCP servers](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/) or wrapping individual fetch requests, Truto maps Firma's complex REST resources into a standardized schema that LLMs intuitively understand.

Every integration on Truto is represented as a comprehensive JSON object mapping the underlying product's API behavior. Truto handles all the boilerplate: authentication (OAuth/API keys), pagination normalization, and dynamic schema injection.

**A critical note on rate limits:** Truto does not retry, throttle, or apply backoff on rate limit errors. When the Firma API returns an HTTP 429 Too Many Requests, Truto passes that exact error down to the caller. However, Truto normalizes the upstream rate limit information into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF specification. Your agent execution loop or application logic is fully responsible for intercepting these 429s, reading the normalized headers, and applying the appropriate retry and backoff logic. Truto will not absorb these errors for you.

## Firma AI Agents Integration: Hero Tools

Truto provides dozens of tools for Firma, but a few specific operations unlock the highest leverage for autonomous workflows. Here are the core tools you will use to build agentic signing workflows.

### create_a_firma_signing_request

Creates a new signing request either from a base64-encoded PDF document or an existing template. This is the starting point for any contract automation. The agent must specify either the document payload or the `template_id` (but not both).

> "Draft a new NDA signing request using template ID 'tpl_98765'. Set the expiration to 48 hours and enable editing before sending."

### firma_signing_requests_partial_update

Partially updates an existing signing request. Because Firma strictly requires updates to target either properties OR a single recipient, Truto's tool schema explicitly defines these constraints so the LLM knows exactly how to format the payload to avoid a 400 error.

> "Update the pending vendor agreement (ID: req_123) to change the description to 'Revised Q3 Pricing'. Do not modify the recipients in this step."

### create_a_firma_jwt_generate_signing_request

Generates a JWT token for embedding a signing request editor directly into your application. This tool returns the token and expiration data, allowing the agent to provision temporary access for external users.

> "Generate an embedded editor JWT for the partnership agreement (ID: req_456) so the user can review the fields before we send it out."

### create_a_firma_jwt_revoke_signing_request

Revokes a previously generated signing request JWT token. This is a critical security tool that allows the AI agent to clean up ephemeral access after a user has finished interacting with an embedded editor.

> "The user has finished editing the partnership agreement. Revoke the JWT (ID: jwt_789) immediately to secure the session."

### firma_signing_requests_send

Triggers the actual email delivery of a signing request to all defined recipients. This moves the document out of the draft state and locks further modifications to the core document payload.

> "The vendor agreement has been reviewed and approved. Send the signing request to all recipients now."

### list_all_firma_signing_request_fields

Lists all fields for a specific signing request, including their current values and completion status. Agents use this to audit whether required signatures or text fields have been filled out by the counterparty.

> "Check the fields on the completed employment contract (ID: req_321) and list all the values the employee entered for their tax information."

For the complete inventory of Firma tools, schemas, and query parameters, visit the [Firma integration page](https://truto.one/integrations/detail/firma).

## Workflows in Action

Providing individual tools to an LLM is only useful if the agent can chain them together to solve complex business logic. Here is how specific personas use these tools to execute multi-step Firma workflows.

### Scenario 1: Automated Contract Generation and Embedded Sending

**Persona:** Revenue Operations 

When a sales rep moves a deal to "Closed Won" in the CRM, they need to generate a specific service agreement, review it in an embedded editor, and send it to the client.

> "Generate a service agreement from our standard template for the new Acme Corp deal. Give me an embedded link so I can review the custom fields, and once I approve, I will ask you to send it."

1. The agent calls `create_a_firma_signing_request` using the known template ID for standard service agreements.
2. The agent calls `create_a_firma_jwt_generate_signing_request` to generate the session token.
3. The agent formats the output URL and returns it to the sales rep.

*Output:* The user receives a direct, secure link to the embedded Firma editor. Once they type "Looks good, send it", the agent immediately calls `firma_signing_requests_send` and subsequently calls `create_a_firma_jwt_revoke_signing_request` to kill the editor session.

### Scenario 2: Document Correction and Active Link Revocation

**Persona:** Compliance / Security Admin

An employee realizes they sent a contract with an incorrect expiration date and a misspelled recipient email. They need the agent to halt the process, correct the data, and reissue.

> "I sent the MSA to John Doe yesterday, but the expiration is wrong and his email is misspelled. Cancel the current request, fix his email to john.doe@example.com, set the expiration to 72 hours, and resend it."

1. The agent calls `list_all_firma_signing_requests` filtering by the signer name "John Doe" to locate the active request ID.
2. The agent calls `firma_signing_requests_cancel` to halt the current active email link.
3. The agent calls `firma_signing_requests_partial_update` to update the expiration hours to 72.
4. The agent calls `firma_signing_requests_partial_update` a second time (respecting the mutually exclusive quirk) to update the recipient's email.
5. The agent calls `firma_signing_requests_send` to issue the corrected document.

*Output:* The user receives confirmation that the original links are dead, the payload was corrected, and the new contract is out for signature.

## Building Multi-Step Workflows

To build these autonomous workflows, your system needs to fetch the tool definitions from Truto, register them with your LLM framework, and handle the execution loop.

Truto integrates seamlessly with LangChain, Vercel AI SDK, and other frameworks. Here is a concrete architecture for setting up an autonomous LangChain loop that handles Truto's pass-through rate limits.

```mermaid
sequenceDiagram
  participant App as Your App (LangChain)
  participant Truto as Truto API
  participant Firma as Firma API
  
  App->>Truto: GET /integrated-account/{id}/tools
  Truto-->>App: Return Firma JSON tool schemas
  App->>App: Bind tools to LLM
  App->>Truto: Execute firma_signing_requests_send
  Truto->>Firma: POST /signing-requests/{id}/send
  Firma-->>Truto: 429 Too Many Requests
  Truto-->>App: 429 (Pass-through with standardized headers)
  App->>App: Parse ratelimit-reset header
  App->>App: Wait for backoff period
  App->>Truto: Retry execution
```

### Implementation with LangChain.js

Using the `truto-langchainjs-toolset`, you can easily fetch the tools and build a responsive agent. Because Truto passes HTTP 429s directly to you, your agent logic must explicitly handle these errors. 

```typescript
import { TrutoToolManager } from "@trutohq/truto-langchainjs-toolset";
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";

async function runFirmaAgent() {
  // 1. Initialize the Tool Manager with your Truto environment
  const toolManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
    environment: "production"
  });

  // 2. Fetch all Firma tools for the specific integrated account
  const tools = await toolManager.getTools(process.env.FIRMA_INTEGRATED_ACCOUNT_ID);

  const llm = new ChatOpenAI({
    modelName: "gpt-4-turbo",
    temperature: 0,
  });

  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a legal operations assistant. You manage Firma signing requests. If a tool call fails with a 429 rate limit error, you must notify the user and wait before retrying."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);

  const agent = await createOpenAIToolsAgent({
    llm,
    tools,
    prompt,
  });

  const executor = new AgentExecutor({
    agent,
    tools,
    maxIterations: 10,
    // Custom error handling is critical here because Truto passes 
    // 429 rate limits directly to the caller without automatic retries.
    handleParsingErrors: true,
  });

  try {
    const result = await executor.invoke({
      input: "Cancel the pending MSA for Client X, change the expiration to 48 hours, and resend it."
    });
    console.log(result.output);
  } catch (error) {
    // Implement your rate limit backoff logic here by reading the 
    // standard 'ratelimit-reset' header passed through by Truto.
    if (error.status === 429) {
      const resetTime = error.headers['ratelimit-reset'];
      console.error(`Rate limited by Firma. Retry after ${resetTime} seconds.`);
    } else {
      console.error("Agent execution failed:", error);
    }
  }
}

runFirmaAgent();
```

In this setup, the `TrutoToolManager` dynamically queries the `/tools` endpoint. If you update a tool description in the Truto UI to give the LLM better instructions (e.g., teaching it about the mutually exclusive `PATCH` behavior), those changes reflect instantly in your next execution - zero code deploys required.

## Moving Beyond Brittle Wrappers

Hardcoding API integrations for AI agents is a trap. You spend weeks building standard `@tool` wrappers, only to discover that the LLM hallucinates payloads, misunderstands endpoint relationships, and fails at state-dependent transitions.

By leveraging Truto's dynamic `/tools` endpoint, you abstract away the authentication and pagination boilerplate while retaining absolute control over the execution loop and rate limit handling. Your AI agents gain robust, schema-aware access to Firma's deepest functionality - from embedded JWT generation to complex document lifecycle management - allowing your engineering team to focus on building agentic reasoning instead of maintaining integration wrappers.

> Ready to give your AI agents reliable, unified access to Firma and 150+ other enterprise SaaS platforms? Book a technical deep dive with our engineering team.
>
> [Talk to us](https://cal.com/truto/partner-with-truto)