Skip to main content
Custom code integrations let you run your own server-side logic as tools that agents call during conversations. Instead of pointing an agent at a single API endpoint, you build a middleware layer that can combine multiple data sources, apply business rules, transform responses, and handle complex orchestration — all behind a single tool the agent calls naturally.

​
When to Use Custom Code

Use custom code when:
  • A tool needs to call multiple APIs before returning a single response to the agent
  • You need to transform, filter, or enrich data before the agent sees it
  • Business rules, validation, or authorization logic should run server-side
  • The integration requires custom authentication flows or token management
  • You want to abstract complex backend systems behind a simple interface for the agent
For simple single-endpoint API calls, HTTP integrations are easier and do not require your own server. For no-code automation, Zapier may be a better fit.

​
How It Works

  1. You build an endpoint on your server that accepts requests from Simple AI
  2. You create an HTTP tool on your agent that points to your endpoint
  3. During a call, the agent calls your endpoint like any other tool
  4. Your server runs whatever logic you need — database queries, multi-API orchestration, business rules
  5. Your server returns a clean JSON response that the agent uses to continue the conversation
Your endpoint is a normal web server. You can write it in any language, use any framework, and deploy it anywhere.

​
Example: Combined Customer Lookup

Instead of giving the agent three separate tools (CRM lookup, billing check, ticket search), build one endpoint that combines all three: 
Agent calls: POST https://your-server.com/api/simple-ai/customer-lookup
Body: { "phone_number": "+15551234567" }

Your server:
  1. Queries your CRM for the customer record
  2. Calls your billing API to get payment status and plan details
  3. Calls your ticketing system for open support cases
  4. Combines everything into a single response

Response:
{
  "customer_name": "Sarah Johnson",
  "account_id": "ACCT-789",
  "plan": "Enterprise",
  "payment_status": "current",
  "open_tickets": [
    { "id": "T-456", "subject": "Billing discrepancy", "status": "open" }
  ]
}
The agent gets everything it needs in one call, and your backend handles the complexity.

​
Example: Eligibility Check with Business Rules

An insurance agent needs to check whether a caller is eligible for a specific plan. The rules are complex and change frequently, so they live in your backend: 
Agent calls: POST https://your-server.com/api/simple-ai/eligibility-check
Body: { "member_id": "MBR-123", "plan_code": "GOLD-2026" }

Your server:
  1. Looks up the member in your enrollment system
  2. Checks their current coverage, age, and state of residence
  3. Applies the latest eligibility rules for the requested plan
  4. Returns a clear yes/no with explanation

Response:
{
  "eligible": true,
  "reason": "Member meets all criteria for GOLD-2026",
  "effective_date": "2026-05-01",
  "monthly_premium": "$425.00"
}
The agent can communicate the result without understanding the underlying rules.

​
Example: Order Action with Side Effects

A support agent needs to process a return. This involves multiple steps that should happen atomically on your backend: 
Agent calls: POST https://your-server.com/api/simple-ai/process-return
Body: { "order_id": "ORD-789", "reason": "defective", "items": ["SKU-A", "SKU-B"] }

Your server:
  1. Validates the order exists and is eligible for return
  2. Creates the return in your fulfillment system
  3. Initiates the refund in your payment processor
  4. Sends a return shipping label to the customer's email
  5. Updates the order status in your OMS

Response:
{
  "return_id": "RET-456",
  "refund_amount": "$89.99",
  "refund_method": "original payment method",
  "label_sent_to": "sarah@example.com",
  "estimated_refund": "3-5 business days"
}
The agent tells the customer the return is processed and a label has been sent — your backend handled all the coordination.

​
Building Your Endpoint

​
Request Format

When the agent calls your tool, Simple AI sends a POST request with:
  • Headers — whatever you configured on the HTTP tool (typically an auth token)
  • Body — JSON with the parameters the agent filled in based on the conversation

​
Response Format

Return a JSON object with the data the agent should communicate. Keep it concise — only include fields the agent will actually say out loud or use to make decisions.

​
Error Handling

If your endpoint returns an error (4xx, 5xx) or times out, the agent handles it gracefully and continues the conversation. Return clear error messages when possible so the agent can tell the caller what went wrong: 
{
  "error": true,
  "message": "Order ORD-789 is not eligible for return. The return window has expired."
}

​
Best Practices

  • Keep responses concise — the agent reads the response and communicates it to the caller. Large payloads with irrelevant fields slow everything down.
  • Use descriptive tool descriptions — the agent decides when to call your tool based on its description. Be specific about the trigger conditions.
  • Handle errors clearly — return human-readable error messages so the agent can explain the problem to the caller instead of saying “something went wrong.”
  • Secure your endpoints — use authentication headers and validate them on your server. Your endpoint will receive call data that may include sensitive information.
  • Log requests — log incoming requests and outgoing responses so you can debug issues and audit what happened during calls.
  • Scope to the right nodes — in flow-based agents, assign your custom code tools only to the nodes where they are relevant.