Agentspan allows you to securely pass credentials to tools. Secrets are resolved from the server's secret store at execution time and injected as environment variables for worker tools. For HTTP/MCP tools, you can use ${NAME} substitution in headers.
Methods of injection:
- Worker Tools: Define
credentials: ['SECRET_NAME'] in the tool options. The secret is injected into process.env during the tool call. - Explicit Fetching: Use
getCredential('SECRET_NAME') inside the tool logic. - HTTP Tools: Use
${SECRET_NAME} in the headers configuration. - Agent Level: Pass
credentials: [...] to the Agent constructor to authorize the agent to use those secrets. - Call Time: Pass
credentials: [...] in runtime.run(agent, prompt, { credentials: [...] }).
Strict Mode: Set credentialStrictMode: true (or AGENTSPAN_CREDENTIAL_STRICT_MODE=true) to ensure that missing secrets cause a hard error instead of falling back to environment variables.
import { Agent, tool, httpTool, getCredential } from '@conductor-oss/conductor-agent-sdk';
// A worker tool: the secret is injected into the worker's process.env for the call
const dbLookup = tool(
async (args: { query: string }) => {
const key = process.env.DB_API_KEY ?? '';
return { ok: key !== '' };
},
{
name: 'db_lookup',
description: 'Look up data.',
inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
credentials: ['DB_API_KEY'],
},
);
// Or fetch a credential explicitly inside a tool
const analytics = tool(
async (args: { topic: string }) => {
const key = await getCredential('ANALYTICS_KEY');
return { topic: args.topic, ok: !!key };
},
{
name: 'analytics',
description: 'Query analytics.',
inputSchema: {
type: 'object',
properties: { topic: { type: 'string' } },
},
credentials: ['ANALYTICS_KEY']
},
);
// HTTP tool with ${CRED} header substitution
const searchApi = httpTool({
name: 'search_api',
description: 'Search.',
url: 'https://api.example.com/search',
headers: { Authorization: 'Bearer ${SEARCH_API_KEY}' },
credentials: ['SEARCH_API_KEY'],
});
const agent = new Agent({
name: 'credentialed_agent',
model: 'anthropic/claude-sonnet-4-6',
instructions: '…',
tools: [dbLookup, analytics, searchApi],
credentials: ['DB_API_KEY', 'ANALYTICS_KEY', 'SEARCH_API_KEY'],
});
