• Documentation
    • Search documentation
    karat

    +

    K

    API Reference ↗
    Developer toolchainAgentsCore conceptsConnect to external systems

    Connect to external systems

    Beta

    Agents are in the beta phase of development and may not be available on your enrollment. Functionality may change during active development.

    Connecting to external systems using sources is not supported on CBAC-enabled environments.

    When your agent needs to reach an external system (such as a monitoring service, a webhook, or a third-party API), or requires a secret like an API key or token, use a source.

    A source provides two things to your agent at runtime:

    • Network egress to the host the source points to. Sources contribute network policies automatically, so you do not need to configure egress separately.
    • Secrets delivered into the running agent container at /app/var/run/source_credentials.json.

    Read source credentials

    Foundry writes resolved secrets to /app/var/run/source_credentials.json. The file has the following shape:

    Copied!
    1
2
3
4
5
{
  "<sourceApiName>": {
    "<secretApiName>": "<secret value>"
  }
}

    Read it from your agent code:

    Copied!
    1
2
3
4
5
6
7
8
9
import * as fs from "fs";

type SourceCredentials = Record<string, Record<string, string>>;

const creds: SourceCredentials = JSON.parse(
  fs.readFileSync("/app/var/run/source_credentials.json", "utf-8"),
);

const externalSystemApiKey = creds["example"]?.["api_key"];

    Keep the following in mind when reading credentials:

    • The file contents will be {} if the credentials could not be resolved.
    • Do not cache the file contents in memory. The file is replaced atomically (as a single, indivisible operation, with no partial or intermediate state visible), so read it when you need the current value.

    Next steps