Skip to main content

Code agents

A code agent is an agent your team writes in code, with the framework it already uses. You give Orchestrate the source. Orchestrate builds it into a signed image inside your cluster, runs it, and puts the same controls around it as around an agent made in the console: the Model Gateway, policy, guardrails, the approval gate, traces, evals and the audit log.

Frameworkframework valueEntrypoint
Google Agent Development Kit (ADK)adkAn Agent or LlmAgent, or an App
LangGraphlanggraphA compiled graph whose state has messages
LangChainlanggraphAn agent from create_agent, which is a LangGraph graph
CrewAIcrewaiA Crew, or a function that returns one
OpenAI Agents SDKopenai-agentsAn Agent
LlamaIndexllamaindexA FunctionAgent, ReActAgent or AgentWorkflow, or a chat engine
Plain Pythonpythonasync def chat(messages, *, context)

Code agents are Python 3.12.

Before you start​

Code agents are off until your operator turns them on. They run customer code, so they need more from the cluster than the rest of Orchestrate:

  • agents.enabled: true in the Helm values.
  • A cluster that enforces NetworkPolicy, such as Cilium or Calico. Each agent runs behind a default-deny policy that keeps it away from the platform's own services. Your operator states that the cluster enforces it with agents.networkPolicy.enforced: true. Without that statement, deploys are refused.
  • Vault for source credentials, agent secrets and runtime keys.
  • A registry project for agent images, with push credentials for the build.
  • A Python package index for the build: public PyPI on a connected install, your own mirror, or the offline package index that ships in the release bundle.
  • The licence includes code agents. A licence can cap the number of code agents, build minutes per month and runtime replicas.

See Configuration.

The manifest: orchestrate.yaml​

Every code agent has an orchestrate.yaml at the root of its source, or in the folder you name for a monorepo:

orchestrate.yaml
apiVersion: orchestrate.vois.ai/v1
kind: Agent
name: support-bot # lowercase, 2 to 40 characters; the agent's name
description: Answers billing questions.
framework: langgraph # adk | langgraph | crewai | openai-agents | llamaindex | python
entrypoint: app.graph:graph # module.path:attribute
python:
dependencies:
file: requirements.txt # or pyproject.toml
installer: pip # pip | uv
build:
test_command: pytest -q # optional; a failing test fails the build
runtime:
resources: cpu-small # cpu-small | cpu-medium | cpu-large | gpu-1
replicas: 2 # or autoscaling: {min: 1, max: 5, target_cpu_percent: 70}
timeout_seconds: 300
env:
LOG_LEVEL: info
secrets: # names only; values are set in the console
- name: STRIPE_API_KEY
models:
default: qwen2.5:1.5b
allowed: [qwen2.5:1.5b]
eval:
suites:
- name: billing-regression # must pass before promotion, when the project requires it
file: evals/billing.json # optional; creates the suite if it doesn't exist
network:
egress: # extra destinations, as CIDRs
- cidr: 10.20.0.0/16
ports: [443]

Orchestrate checks the manifest at every intake and refuses it with a list of problems, each with its path. It refuses, among other things, a secret value in the file, a credential-looking value under env, platform-owned variable names (OPENAI_*, VOIS_*, OTEL_* and similar), and egress to loopback, link-local or cloud-metadata addresses. Private address ranges can be opened only where your operator allows them.

voisctl agent validate runs the same checks on your machine.

How your code reaches models and tools​

Orchestrate runs your entrypoint behind its adapter, which serves the agent on an OpenAI Chat Completions endpoint. You don't write a server.

  • Models. OPENAI_BASE_URL and OPENAI_API_KEY point the framework's ordinary OpenAI client at the Model Gateway, with an agent key that Orchestrate mints for the deployment. Every model call is checked against the agent's model policy, metered to the agent and audited. VOIS_DEFAULT_MODEL holds models.default.
  • Platform tools. The project's connectors and built-in tools are offered to the agent through the platform's MCP tool server. The adapter registers it with your framework. A tool call there goes through policy, the approval gate and the audit log, as for a console-made agent.
  • Traces. The adapter exports OpenTelemetry spans to the platform, so a run's steps, tool calls and model calls appear in Runs & traces. Prompt and answer content in spans is off by default, and redacted when you switch it on.
  • Other agents. VOIS_A2A_URL is where the agent reaches other agents of its project. See Agents calling agents.

Framework telemetry that would call out to its vendor is switched off.

Create a code agent​

  1. Open Agents, choose New agent, then From code.
  2. Pick a source:
    • Template. A starter agent for one framework.
    • Git repository. HTTPS or SSH, a branch, and optionally a folder. Credentials (a token, or an SSH key with its known hosts) go to Vault. Builds start on a signed webhook from your git server, on polling, or by hand.
    • Upload. A .tar.gz or .zip of the source.
  3. Review the manifest. Errors are listed with their path.
  4. Enter the values of the secrets the manifest names. Setting secrets needs the project admin role.
  5. Create. The first build starts. For a git source with a webhook, the webhook address and secret are shown once.

From a terminal, voisctl agent push --project <project> [--wait] [--follow] packs the current folder, checks it, and starts a build. voisctl agent init --framework <framework> starts a new agent from a template.

The pipeline​

Each build runs in your cluster:

StageWhat happens
fetchClones the exact commit, or reads the uploaded archive.
validateChecks the manifest and the archive.
renderWrites the Dockerfile from the manifest, on a curated base image for the framework. You never write a Dockerfile.
installInstalls your dependencies from the configured package index.
buildBuilds the image.
testRuns build.test_command, if there is one.
pushPushes the image to your registry.
signRecords the image digest and its SBOM in the audit chain. A deploy refuses any image Orchestrate didn't build.

A successful build is a new version. With auto-deploy on, the default, the version is deployed to staging with one replica, and the eval suites named in the manifest run against it.

The Pipeline tab shows every stage with its status, duration and log, which streams while the build runs. You can cancel a build, and a failed build says which stage failed and why.

Promote, roll back and scale​

ActionWhoWhat happens
PromotedeveloperThe version becomes live, at the manifest's live size. If the project requires passing evals, a failing or missing suite blocks it. A project admin can override with a reason, which is audited. The Versions tab compares the version's eval results with the live version's.
Roll backdeveloperSwitches to a version that was live before. The previous live version stays warm with one replica, so a rollback takes seconds.
ScaledeveloperChange replicas, or scale a version to zero. A live agent at zero replicas answers 503.
RestartdeveloperRolls the pods and applies changed secret values.
UndeploydeveloperRemoves a version's deployment. Taking the live version offline must be confirmed.

Each deployment gets its own agent key, which is revoked when the version scales to zero or is undeployed.

The Runtime tab shows replicas, restarts, latency and recent errors, and warns when the cluster doesn't enforce NetworkPolicy.

Reach the agent​

A code agent is reached exactly like a console-made one: the Agent API (with token streaming and client tools), the hosted chat and widget, channels, A2A, voice and phone calls, and the Playground, where you can also pick a staging or older version. Console-made agents can call it as a tool.

Quotas​

A platform admin can set per-project quotas on the Licence page: the number of code agents, builds at once, build minutes per month, and runtime CPU, memory and GPUs. The licence's install-wide limits apply on top. A quota stops new agents, builds and deploys. Agents already running keep serving.

Offline installs​

The release bundle carries the curated base images and an offline package index with pinned wheels for every framework, so builds work with no internet. An operator can add wheels on site with voisctl wheelhouse add. If a package your agent needs isn't in the index, the install stage fails and names it.

Was this page helpful?