Agents

Agents in Orbitype can use tools to fetch data, call services, and perform structured tasks during a run. You can start with predefined tools in the UI and extend your agent with custom tools at any time.

How to create an agent

1. Go to Agents and click New.

2. Add a short description and system prompt.

3. Select one or more predefined tools.

4. Save the agent. It is ready to use immediately.

How to add custom tools

Each custom tool is defined as a JSON object with 4 fields:

{
  "name": "tool_name",
  "description": "When and why the agent should use this tool",
  "func": "async ({ ...inputs, ...runtimeHelpers }) => { ... }",
  "schema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

Field reference

• name (string): unique tool identifier. Recommended format: lowercase + underscores (example: google_search).

• description (string): short instruction that helps the agent decide when to use the tool.

• func (string): async JavaScript function that executes the tool logic and returns data.

• schema (object): JSON schema for the tool input.

Schema guide

• Top-level should be { "type": "object" }.

• Define inputs in properties.

• Define mandatory inputs in required.

• Add clear description for each property to improve tool-call quality.

Runtime input in func

Your function receives an object containing:

• the fields defined in your schema (for example query, url)

• runtime helpers available in your environment (for example search, browser, AI, database, etc., depending on setup)

Tip: always validate/normalize user input inside the function and return predictable JSON.

Copy-paste example

{
  "name": "google_search",
  "description": "Searches the web for relevant information, solutions, and best practices.",
  "func": "async ({ query, serp }) => {\n  const normalizedQuery = String(query ?? \"\").trim()\n  if (!normalizedQuery) return { query: normalizedQuery, results: [], count: 0 }\n\n  const rawResults = await serp.search(normalizedQuery)\n  const results = Array.isArray(rawResults) ? rawResults : []\n\n  return {\n    query: normalizedQuery,\n    results,\n    count: results.length\n  }\n}",
  "schema": {
    "type": "object",
    "required": ["query"],
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query"
      }
    }
  }
}

Best practices

• Keep one tool focused on one job.

• Use explicit, stable output structures.

• Handle empty input and errors gracefully.

• Prefer small composable tools over one large multi-purpose tool.

Common issues

• Tool not called: improve description and schema descriptions so usage intent is clearer.

• Validation mismatch: ensure your function expects the same fields defined in schema.

• Runtime error: wrap external calls in try/catch and return a structured error object.

In functions, agency is injected automatically. It gives you access to your configured agents by slug.

Use agency.get(slug) to select an agent, then call run(prompt) to execute it.

• agency.get(slug) selects the agent you want to use

• agent.run(prompt) runs that agent and returns the result

Example:

async ({ agency }) => {
  const agent = agency.get("immo_research_agent")

  if (!agent) {
    return { error: "Agent not found: immo_research_agent" }
  }

  try {
    const run = await agent.run("start prompt for my Agent")
    return { run }
  } catch (e) {
    return { error: String(e) }
  }
}