Agent development

An agent framework built for AI‑assisted development

Tactet has its own agent framework. An agent is a JSON document with one structure and 20 commands, and its values can be Python expressions. One schema describes all of it. Draft with AI, the code editor and validation work from that schema, in the development environment that is part of the UI.

Agent framework

An agent is JSON with Python expressions

Below is a complete agent. It searches a knowledge base for the user’s request and has a model write the answer from the best passages.

kb_answer.json
{
  "functions": {
    "main": {
1Every run starts in the function named main.      "commands": {
        "api": {
2The api command calls the API that the knowledgeBase profile names. The URL and the credentials are in the profile.          "profile": "knowledgeBase",
          "queryParams": { "q": "{ sys.query }" }
3A string enclosed in braces is a Python expression. sys.query contains the user’s request.        },
        "var": {
          "passages": "{ [hit['text'] for hit in result[:5]] }"
4result contains what the last command returned. This expression keeps the text of the first five hits in a variable named passages.        },
        "llm": {
          "profile": "gpt5_mini",
          "prompt": "answer",
5The llm command names a prompt. The prompt’s text is kept outside the definition and reads passages. The answer is streamed to the user.          "streamOutput": true
        }
      }
    }
  }
}
  1. 1Every run starts in the function named main.
  2. 2The api command calls the API that the knowledgeBase profile names. The URL and the credentials are in the profile.
  3. 3A string enclosed in braces is a Python expression. sys.query contains the user’s request.
  4. 4result contains what the last command returned. This expression keeps the text of the first five hits in a variable named passages.
  5. 5The llm command names a prompt. The prompt’s text is kept outside the definition and reads passages. The answer is streamed to the user.

Every value keeps its JSON meaning, with one extension: a string enclosed in braces is a Python expression, evaluated when the agent runs. Any other string is plain text. An expression can read variables, the result of the last command, and what the runtime provides, such as the user’s request. Each expression is checked when the agent is validated and runs in a controlled runtime.

Every agent has the same structure

An agent is a set of functions. Each function contains an ordered map of commands. The commands run in the order in which they are declared.

Agent structure
{ "functions": { "main": { "commands": { "api": { … }, "var": { … }, "llm": { … } } }, "order_status": { "commands": { "db": { … }, "return": { … } } } } } Agent: a set of functions Function. Every run starts in main Commands, run in this order Another function Its commands, in order
Commands
Variablesvar
LLM interactionllmmemory
External systemsapidb
Human-in-the-loopask
Agent outputoutput
Agent terminationendfail
Observabilityprogresstracelog

A command is a key, and its value contains the command’s fields: an object for most commands, and a single value for simple ones such as progress and return. To use a command a second time in the same function, add a suffix after a dot: api, then api.2. The syntax and structure pages explain all the rules.

Every run starts in main. Another function runs when a function calls it with func or parallel, or when a model calls it as a tool.

A function can be a tool for the model

This agent answers questions about orders. Its function getOrder looks up one order through an API, and the model decides when to call it. Agents are written in JSONC, a form of JSON that allows comments, so this one includes a few.

orders.jsonc
{
  // Answers questions about orders.
  // The model calls getOrder when it needs one.
  "functions": {
    "getOrder": {
      "description": "Looks up one order by its number.",
      "args": { "orderId": { "type": "str" } },
1A function with a description and typed arguments can be given to a model as a tool. The model reads both, decides when it needs the function, and supplies the arguments.      "commands": {
        "progress": "Looking up the order",
2Each of these two commands is a single line. The progress command shows the user a short message while the agent works. The log command writes a line to the agent server’s log, which stays in your environment.        "log": "{ f'Order {orderId} requested by {sys.userEmail}' }",
        "api": {
3The api command calls the API named by the profile. The host, credentials, and headers come from the profile; only the path comes from the agent. The parsed response is placed in result.          "profile": "orders",
          "path": "{ f'/orders/{orderId}' }"
        },
        "trace": "{ f'Status: {result['status']}' }",
4The trace command writes to the execution trace that you read while validating a draft. In production it does nothing.        "progress.done": "Found the order",
5To use a command a second time in the same function, add a dot and a suffix to its name. The suffix can be any word or number; it only keeps the two keys distinct.        "return": "{ result }"   // the order goes back to the model
      }
    },
    "main": {
      "commands": {
        "llm": {
          "profile": "gpt5_mini",
          "prompt": "orders",
          "functions": ["getOrder"],
6Listing getOrder here gives the model that function as a tool. The model calls it whenever a question needs an order looked up.          "streamOutput": true
        }
      }
    }
  }
}
  1. 1A function with a description and typed arguments can be given to a model as a tool. The model reads both, decides when it needs the function, and supplies the arguments.
  2. 2Each of these two commands is a single line. The progress command shows the user a short message while the agent works. The log command writes a line to the agent server’s log, which stays in your environment.
  3. 3The api command calls the API named by the profile. The host, credentials, and headers come from the profile; only the path comes from the agent. The parsed response is placed in result.
  4. 4The trace command writes to the execution trace that you read while validating a draft. In production it does nothing.
  5. 5To use a command a second time in the same function, add a dot and a suffix to its name. The suffix can be any word or number; it only keeps the two keys distinct.
  6. 6Listing getOrder here gives the model that function as a tool. The model calls it whenever a question needs an order looked up.

Systems and prompts are defined outside the agent

An agent names the systems it calls and the prompts it sends. The connection details are in platform-wide profiles, and the text of each prompt is in the agent’s meta. This agent lists a user’s open IT tickets and has a model say where each one stands.

{
  "functions": {
    "main": {
      "commands": {
        "api": {
          "profile": "helpdesk",
          "path": "/tickets",
          "queryParams": {
            "user": "{ sys.userEmail }",
            "status": "open"
          }
        },
        "var": {
          "tickets": "{ result }"
        },
        "llm": {
          "profile": "gpt5_mini",
          "prompt": "ticket_status"
        },
        "output": "{ result }"
      }
    }
  }
}
API profile helpdesk URLhttps://helpdesk.example.com/api HeaderAuthorization: { f"Bearer {sys.secret['HELPDESK_KEY']}" } Pool8 connections, 10 s timeout, 3 retries One profile for every agent that calls the helpdesk.
LLM profile gpt5_mini VendorOpenAI, gpt-5-mini Key{ sys.secret['OPENAI_API_KEY'] } PricesPer million tokens in and out, for the cost report Six adapters: OpenAI, Anthropic, Gemini, Ollama, vLLM, SGLang.
Prompt ticket_status SystemYou are the IT helpdesk. Say where each open ticket stands, in under 80 words. User{ f'{sys.query} Open tickets: {tickets}' } Scopeconversation Edited with the draft, on its Prompts tab.

A profile is shared by every agent that names it. A secret is read from the vault by name, so its value appears in neither the profile nor the agent. A prompt’s system and user text are written like any other string: plain text, or a Python expression that reads the agent’s variables.

The agent runtime handles everything the agent does not specify: credentials, connections to outside systems, streaming, conversation memory, pauses for a person’s answer, and the time and cost limits for every run.

Development environment

Draft, edit, validate, publish

The UI includes a complete development environment for agents. An agent goes through four steps before users can run it.

Draft with AI

Draft with AI writes the first version of an agent from a description of what the agent should do. It works from the same schema that the editor and validation use, and it knows the profiles and prompts of your account. It has never seen your APIs and databases, so it leaves paths, queries and parameters empty, with a comment that says what belongs there. It can also change an existing draft, and it keeps everything your request does not touch.

Try the Draft with AI demo with your own description or one of the examples.

Edit

A draft is private to the developer who created it. The code editor is built on Monaco, the editor inside Visual Studio Code, and it understands the agent language. It suggests the commands and fields allowed where you are typing, and it points out mistakes as you type.

Validate

Validation checks the definition against the schema and the security rules. It also confirms that everything the agent names exists in the account. The agent server then runs the draft against a sample question and shows the trace: every command that ran, the values it received, and what it returned. A draft cannot be published until it validates.

The Trace demo shows a trace of a running agent.

Publish

Publishing gives the agent a version and makes it available to users. The developer then describes the agent in plain English. Search indexes that description, and users find the agent by asking for what it does in their own words. When several developers change the same agent, each works on a separate draft and merges the others’ changes before publishing.

Where to read more

The agent definition section explains the structure of an agent, its variables, and its Python expressions in detail. The command reference describes every command. The getting started guide explains how to write and run your first agent.