CallFunc — Developer Reference

This manual shows you how to turn the three demo HTTP endpoints (get_schedule, get_speaker, book_meeting) into tools your Perxona agent can call — and, just as importantly, how to write them so the LLM actually understands when and how to use them.

Companion docs: API (authoritative schemas).

1. How an LLM “sees” a tool

When the agent runs, Perxona hands the model a list of tools. Each tool is essentially this (the same shape OpenAI and Anthropic use under the hood):

{
  "name": "get_schedule",
  "description": "List conference sessions. Optionally filter by day, track, or speaker.",
  "parameters": { /* the INPUT JSON Schema */ }
}

On every turn the model asks itself, using only that text:

1. Should I call a tool at all? → driven by the name + description.
2. Which one? → driven by how distinct the descriptions are from each other.
3. With what arguments? → driven by the input schema (field names, types, required, descriptions, enums, defaults).
4. What did I get back / what do I tell the user? → helped by the output schema (so it knows event_link exists, that count is a number, etc.).

So your job as a builder is to write those four things clearly. That’s the whole craft.

What actually happens on a call (under the hood)

You only build the server + the four text/shape signals. Perxona does the validation, secret injection, the HTTP call, usage limits, and (optionally) the user confirmation.

2. The two building blocks in Perxona

Setting up a tool is always two objects:

• Create one OutboundAPI for the demo server (one base URL + one API key).
• Create three CallFuncs (one per function), all pointing at that OutboundAPI.

CallFuncs live inside a Storyboard’s Panel, so a tool can be available only in the conversation states (panels) where it makes sense.

3. Setup walkthrough

Step 0 — Get your public URL + API key

cd /Users/kilikkuo/Projects/perxona-callfunc-demo
./scripts/run.sh        # terminal 1: server on :8090
./scripts/tunnel.sh     # terminal 2: prints https://<random>.trycloudflare.com
grep API_KEY .env       # your X-API-Key value

Sanity check the public URL (no key needed for health):

curl -s https://<random>.trycloudflare.com/health

Step 1 — Create the OutboundAPI

In the admin console (Backend Core / Outbound API), create one entry:

Step 2 — Create CallFunc #1: get_schedule

Input schema (query params):

{
  "type": "object",
  "properties": {
    "day":     { "type": "string", "description": "Day label ('Day 1') or ISO date ('2026-06-11')." },
    "track":   { "type": "string", "description": "Track substring, e.g. 'AI/ML'." },
    "speaker": { "type": "string", "description": "Speaker name substring." }
  }
}

Output schema (the “Output data” field) — see API §1 for the full block:

{
  "type": "object",
  "properties": {
    "count": { "type": "integer", "description": "Number of sessions returned." },
    "sessions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type":"string"}, "title": {"type":"string"}, "speaker": {"type":"string"},
          "track": {"type":"string"}, "room": {"type":"string"}, "day": {"type":"string"},
          "date": {"type":"string"}, "start": {"type":"string"}, "end": {"type":"string"}
        }
      }
    }
  }
}

Step 3 — Create CallFunc #2: get_speaker

Input schema:

{
  "type": "object",
  "properties": {
    "name": { "type": "string", "description": "Speaker name to search for (substring)." },
    "id":   { "type": "string", "description": "Exact speaker id, e.g. 'spk_chen'." }
  }
}

Output schema → see API §2: count + speakers[] with id, name, title, company, bio, topics[], sessions[].

Step 4 — Create CallFunc #3: book_meeting

Input schema (payload):

{
  "type": "object",
  "required": ["attendee_name", "speaker", "date", "start_time"],
  "properties": {
    "attendee_name":    { "type": "string", "description": "Name of the person requesting the meeting." },
    "speaker":          { "type": "string", "description": "Name of the speaker to meet." },
    "date":             { "type": "string", "description": "Meeting date, YYYY-MM-DD." },
    "start_time":       { "type": "string", "description": "Local start time, 24h HH:MM." },
    "duration_minutes": { "type": "integer", "minimum": 5, "maximum": 240, "default": 30 },
    "attendee_email":   { "type": "string", "description": "Optional attendee email." },
    "topic":            { "type": "string", "description": "Optional meeting topic." }
  }
}

Output schema → see API §3: booking_id, status, mode, summary, speaker, start, end, timezone, event_link, message.

Step 5 — Test it

In a panel conversation, try:

• “What AI/ML talks are on Day 1?” → should call get_schedule(day:"Day 1", track:"AI/ML").
• “Who is Evelyn Chen and what’s she presenting?” → get_speaker(name:"chen").
• “Book me 30 min with Evelyn Chen on June 11 at 4pm about architecture.” → book_meeting(...) → confirmation prompt (because require_confirmation:true) → event created.

4. The craft: writing descriptions & schemas the LLM understands

This is the part that decides whether the agent feels smart or dumb. Some rules of thumb, with before/after.

4.1 Name = the verb the model matches on

Use a clear verb_noun: get_schedule, book_meeting. Keep the three names distinct so the model never has to guess between two similar tools.

4.2 Description = when to use it, not just what it is

The description is read on every turn as the model decides whether to call. Say what it does and the trigger (“use this when…”), plus any limits.

Tips: - Mention what it returns (“returns title, company, bio, topics”) so the model knows the tool can answer the question. - State negative space (“only when the user explicitly wants to book”) to stop premature or accidental calls — especially for writes. - Don’t dump implementation details (DB, framework). The model doesn’t care and it wastes the context the model reasons over.

4.3 Input schema = the argument contract

Every property description is a hint the model uses to fill that field. Be concrete about format, because the model will copy your wording.

• Formats: "Meeting date, YYYY-MM-DD." and "Local start time, 24h HH:MM." make the model emit 2026-06-11 and 16:00 instead of "next Tuesday" or "4 PM".
• required: list the fields the call can’t work without (attendee_name, speaker, date, start_time). The model will keep asking the user until it has them.
• Defaults & bounds: duration_minutes has default: 30, minimum: 5, maximum: 240 — so the model can omit it, and bad values are rejected before they hit your server.
• Enums (not in this demo, but powerful): {"type":"string","enum":["confirmed","tentative"]} constrains the model to valid choices.
• Keep it flat and small. Deeply nested input is harder for the model to fill reliably.

4.4 Output schema = how the model reads the result (and why you were asked to add it)

After the call, the model reads your JSON response. The output schema tells it what fields exist and what they mean, so it can:

• pull the right value into its reply (e.g. surface event_link as a clickable link, or read message back verbatim);
• understand types (it knows count is a number, topics is a list);
• avoid hallucinating fields that aren’t there.

Describe each output field the same way you describe inputs. For book_meeting, noting that event_link is string | null (null in mock mode) and that mode says "google_calendar" vs "mock" lets the agent phrase the confirmation honestly.

4.5 Golden rule

5. Template variables (optional, good to know)

Perxona can inject conversation context into the request without asking the LLM for it, using {$context.x} and {$story.x} placeholders in the URL/headers/fixed params. Example: put the logged-in user’s id in a header as {$context.user_id} so book_meeting doesn’t need the model to pass it. The demo doesn’t require this, but it’s how you keep secrets and known context out of the model’s hands.

6. Safety & UX knobs

For this demo: book_meeting → require_confirmation: true; the two get_* reads → false.

7. Troubleshooting

8. Perxona CallFunc vs. MCP and other agentic tool designs

All modern tool systems share the same core idea you just used: a tool is a name + description + JSON Schema, and the model reasons over that contract. They differ in who hosts the tool, how it’s transported, and what the platform does for you.

Quick comparison

Pros of the Perxona CallFunc approach

• No-code / low-code. Any HTTP API becomes a tool by pasting a URL + JSON Schema. Perfect for vibe coders and for turning an existing backend into agent tools in minutes — no adapter server to write or host (an MCP integration means building and operating a server).
• Batteries included. Encrypted secrets, per-tool usage limits, require_confirmation human-in-the-loop, context templating ({$context}/{$story}), text-to-SQL safety, logging and multi-tenant scoping are all provided. With MCP or native function calling you build all of that yourself.
• Tight product integration. Tools live inside the persona/storyboard flow and can be panel-scoped (available only in the right conversation state), and they ride the same pipeline as memory, guardrails, and the conversation transcript.
• Output schema as a first-class field. You declare what comes back, which helps the model interpret results and keeps responses honest (e.g. mock vs real event_link).

Cons / limits

• Proprietary & platform-locked. Your tools live in Perxona; they’re not portable to other hosts. MCP’s biggest win is reuse — write a tool server once and use it from Claude Desktop, IDEs, and any MCP-compatible client. A CallFunc can’t be reused outside Perxona.
• HTTP request/response only. No local/stdio tools, no streaming or long-running jobs, no stateful tool sessions, and none of MCP’s resources / prompts / sampling primitives. (In the current backend, the DATA_VALIDATION CallFunc type isn’t implemented, and there’s no tool-result caching, batching, or circuit-breaker — it’s one clean round trip.)
• Static configuration. Tools are set up ahead of time in the UI; there’s no runtime discovery like MCP’s tools/list. Changing a tool means editing it in the console.
• You must host a public endpoint. It has to be reachable from Perxona (hence the cloudflared tunnel), and you own its uptime, latency, timeouts, and TLS. MCP servers can run locally next to the client; native functions run inside your own app.
• Schema-dialect coupling. Input/output use JSON Schema (Draft 2020-12) converted to Pydantic via jambo; very exotic schema features may not convert cleanly. Keep schemas simple and flat (which is good practice for the model anyway).

How to think about it

• These approaches aren’t mutually exclusive in spirit — they all rest on name + description + schema. What you learned here transfers directly to MCP and to native function calling.
• Use Perxona CallFunc when you’re shipping inside Perxona and want the fastest path from “an HTTP API exists” to “the agent can use it,” with confirmation/limits/secrets handled for you — exactly this demo.
• Reach for MCP when you want a tool/data server that’s reusable across many AI clients, needs local or stateful access, or wants resources/prompts beyond plain function calls.
• Use native function calling when you’re building your own agent application directly on an LLM API and want end-to-end control of execution.

9. One-page recap

1. Two objects: one OutboundAPI (URL + API key) + one CallFunc per function (name, description, method, path, input schema, output schema, confirm).
2. The model only sees name + description + input schema + output schema — write them for a smart stranger.
3. Description = what it does + when to use it (+ what it returns, + what NOT to do).
4. Input schema = field names, types, required, formats, defaults, enums.
5. Output schema = what comes back, so the model reads results correctly.
6. Writes get require_confirmation: true. Reads don’t.
7. It’s HTTP + managed guardrails, no code — great for speed inside Perxona; MCP wins on reuse/portability and richer primitives; native function calling wins on full control in your own app.