Documentation

You need Git, Python 3, and Docker with Compose. On Windows, run PowerShell with permission to use Docker Desktop.

Clone the repository and run python gaia.py install. The assistant validates dependencies, prepares configuration, and starts the containers.

The flow works from PowerShell. For focused development, run React, FastAPI, or Flutter separately without changing production deployment.

production prioritises stability; dev enables development; hub connects managed services; local keeps the environment on your machine. Choose the mode before generating configuration.

Connect any provider and switch the agent's model with one click. Compare responses between Claude, GPT-4o, or others without reconfiguring anything.

The system prompt, skills, and context are defined once in iAgents Hub. Export the agent to the native format of each target platform — Claude Code, OpenAI Assistants, or GitHub Copilot — or import existing agents with a content preview before confirming.

Name, system instructions (system prompt), model and selected connection, linked skills, persistent memory, knowledge base, and scheduled routines.

When memory is enabled, the agent remembers context from previous conversations. You can view and edit memories from the Memory section.

Automate tasks the agent should run on a regular basis. Define a name, an instruction, and a trigger — manual, webhook, or a cron expression for scheduled execution — without needing an active conversation.

A provider (in Profile → Providers) stores your API key and gives access to its model catalog. Syncing it automatically creates a connection for each available LLM. Assign whichever connection you prefer to each agent.

LLMs charge by tokens: text units of roughly 4 characters each. Each connection accumulates the total input and output tokens consumed. You can view this in the Dashboard and in the Connections list.

Each orchestration accepts 2 to 20 candidates. Stack mode respects the configured order; Balanced mode uses a router connection to rank every candidate against the agent and current message.

The router model does not perform the task. It returns a JSON ranking of candidate connections and a short reason, then execution starts with the best-ranked option for that message.

Connections are attempted in the order you define. This suits a stable priority — based on cost, privacy, latency or provider — without spending tokens on a routing decision.

If a connection is inactive, fails or returns an empty response before the first token, the next one is attempted. Once streaming starts, the model is not switched, so partial responses are never mixed.

The final response includes the selected connection, attempted connections and token usage per connection. Balanced mode also accounts for the router model's usage.

Orchestrations can belong to a group or be shared with it. Sharing grants access to the required connections without duplicating them or turning credentials into public resources.

They include read-only official skills and skills published by registered users. Everyone, including guests, can browse them.

You can create skills in the Skills section and choose whether they are private or public. In guest mode they are private, temporary, and kept only in session memory.

When editing an agent, select the skills you want to include. A skill is used only while it is linked and active. Unlinking affects only that agent; deactivating it from the card's «…» menu prevents every linked agent from using it until it is reactivated.

Go to Profile → Groups and click «Create group». You become the owner automatically. Only registered accounts can create groups; guests do not have access to this feature.

From the group view, click «Invite» and enter the user's public username. They will receive a notification to accept or decline. Group owners and admins can invite and remove members.

Share from a resource card or drag it onto a group in the side panel. Agents cascade-share their private skills, prompts and knowledge; workflows share their agents and dependencies; and LLM orchestrations share the required connections. Secrets are never copied and ownership does not change.

Only three parties can remove a resource from a group: the original resource owner, the group owner, and platform administrators. Other group members can use the resource but cannot revoke sharing.

Resources others have shared with you appear in the corresponding sections with a «Shared» badge. You can use them and open them from the groups panel, but cannot edit or export them — ownership stays with the original creator.

Users without an account (guest mode) cannot create or join groups. Register an account to access collaboration features.

Each node represents an agent step and edges express dependencies and order. Validation detects disconnected graphs and definitions that cannot run safely.

Each run keeps its state and step results. Agents receive workflow content and respond through streaming, just as they do in a normal chat.

Gates let you approve, reject or repeat one branch without rerunning already-approved sibling steps, making human review part of the process.

A workflow can belong to a group or be shared with another. Sharing also grants the required access to its owned agents and their associated private dependencies.

Official sources can deliver agents, skills, prompts or commands, knowledge, tools and workflows. Declared dependencies are imported first and linked to the resource that needs them.

Administrators can track a GitHub repository release or branch. Every resource retains its source and component identity, allowing a package to be updated or removed consistently.

Compatible Python and shell tools are materialised in the catalog, marked as official and attachable as agent dependencies. Automatic execution is not yet enabled in the runtime.

Imports restrict licences, sizes, paths and file types; reject cycles or missing dependencies; and flag dangerous patterns for review before content is materialised.

Official resources are read-only. Link them to retain their origin, make an editable copy when customisation is needed, and sync available updates.

Memory stores text snippets that the agent remembers between conversations. Useful for user preferences, context data, or notes. Enabled per agent.

The knowledge base stores documents (PDF, text, URL). The agent can search them when responding. Useful for technical documentation, FAQs, or any reference content.

Use gaia.py to start, stop, inspect, and manage the deployment from a single entry point.

Review release notes, back up configuration and data, update the image or repository, and validate health before reopening traffic.

Keep the database, uploaded files, and secrets outside containers. Regularly verify that backups can be restored.

Check backend, database, and client health. When something fails, identify the affected service first and inspect its recent logs.

Confirm the URL, port, runtime mode, and that services are running. Try a private window to rule out cache or session state.

Record version, operating system, exact steps, approximate time, and error message. Attach only logs from the affected service.

Verify the API key, base URL, available model, quota, and permissions. Run the connection test before changing the agent.

Never publish keys, tokens, passwords, email addresses, or private content. Replace them with placeholders before sharing screenshots or logs.

Write short, focused system prompts. Avoid repeating instructions already implicit in the model. Every unnecessary line consumes tokens on every message.

Use lightweight models (Haiku, GPT-4o mini) for simple tasks like classification or short summaries. Reserve large models (Opus, GPT-4o) for complex reasoning or critical code generation.

Skills linked to an agent are injected into its conversations. If you have instructions that do not apply to every agent, turn them into a skill and link it only to the agents that need it instead of always including it in the system prompt.

Don't paste entire documents into the system prompt. Load content into the agent's knowledge base: only the relevant part is retrieved for each message, drastically reducing input token usage.

Memory injects context from previous conversations on every turn. If the agent performs independent tasks (text generation, translation), disable it to avoid accumulating unnecessary tokens.

Use low temperature (0.0–0.3) for precision tasks: code, data extraction, classification. Use higher values (0.7–1.0) for creative writing or brainstorming, where variability adds value.